Docs / Formatting and layout

Formatting and layout.

Number formats, fonts, fills, alignment and wrap through set_format, plus the layout tools: widths, heights, freezes, merges, hidden rows and columns, notes and defined names.

`set_format`

Applies a partial format to one range, or to many ranges in one call. Only the keys you pass change; everything else on the cell is left as it is.

{
  "path": "~/models/forecast.xlsx",
  "sheet": "Model",
  "operations": [
    { "range": "A1",      "format": { "bold": true, "font_size": 16 } },
    { "range": "A4:F4",   "format": { "bold": true, "background_color": "#1F4E79", "font_color": "#FFFFFF" } },
    { "range": "B5:F41",  "format": { "number_format": "#,##0" } },
    { "range": "B44:F44", "format": { "number_format": "0.0%" } },
    { "range": "H5:H41",  "format": { "wrap_text": true, "vertical_align": "top" } }
  ]
}

The single-range form is { sheet, range, format }. Prefer operations whenever there is more than one format to apply: one call instead of many.

Format keys

Key	Type	Notes
`number_format`	string	Excel format code. `"$#,##0.00"`, `"0.0%"`, `"#,##0"`, `"@"` for text.
`bold`, `italic`, `underline`, `strike`	boolean
`font_size`	number	Points.
`font_family`	string	`"Calibri"`, `"Arial"`, `"Aptos Narrow"`.
`font_color`	string	CSS color, `"#000000"` or `"red"`.
`background_color`	string or null	Cell fill. `null` clears it. Pair light font colors with a dark fill.
`horizontal_align`	left, center, right
`vertical_align`	top, middle, bottom
`wrap_text`	boolean	Wrap instead of overflow. Pair with a wider column and `vertical_align: "top"` for notes columns.

Cell borders are not supported in this version. Existing borders in the file are preserved; the agent cannot add or change them yet.

Column widths and row heights

set_column_width and set_row_height take pixels. Both have a single form and a bulk operations form; use bulk when groups need different sizes. The default Excel column is about 64 px and a label column is typically 180 to 220; the default row is about 24.

{
  "path": "~/models/forecast.xlsx",
  "sheet": "Model",
  "operations": [
    { "columns": "A", "width": 220 },
    { "columns": "B,C,D,E,F", "width": 96 }
  ]
}

{ "path": "~/models/forecast.xlsx", "sheet": "Model", "operations": [ { "rows": "1", "height": 36 } ] }

Freeze panes

freeze_panes locks the top freeze_rows rows and left freeze_cols columns. The classic model setup is one row and one column. Pass 0 to leave an axis unfrozen. unfreeze_panes removes any freeze on the sheet.

{ "path": "~/models/forecast.xlsx", "sheet": "Model", "freeze_rows": 4, "freeze_cols": 1 }

Merges

merge_cells merges a rectangular range into one visible cell, typically for a section header spanning the columns. unmerge_cells reverses it.

{ "path": "~/models/forecast.xlsx", "sheet": "Model", "range": "A1:F1" }

Hidden rows and columns

hide_rows and show_rows take a comma-separated list of 1-indexed row numbers; hide_columns and show_columns take column letters. Hidden cells keep their data.

{ "path": "~/models/forecast.xlsx", "sheet": "Model", "columns": "D,F,H" }

Cell notes

set_note attaches an Excel-style comment to a cell, for methodology callouts, source citations or caveats that would clutter the cell itself. It overwrites any existing note. delete_note removes it.

{ "path": "~/models/forecast.xlsx", "sheet": "Assumptions", "cell": "B7", "text": "Statutory rate per FY2025 10-K, p. 84." }

Named ranges

define_name creates or replaces a workbook-scoped defined name so formulas can say =Revenue*(1+GrowthRate) instead of =B42*(1+Assumptions!B5). The name must be a valid Excel name and must not look like a cell address; ref is sheet-qualified. The name persists in the saved file.

{ "path": "~/models/forecast.xlsx", "name": "GrowthRate", "ref": "Assumptions!B5" }

Found a mistake? Open an issue or email support@gridpath.dev.