skills/larksuite__cli
1
0
Fork 0
mirror of https://github.com/larksuite/cli.git synced 2026-09-14 18:42:53 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
docs/fix-task-shared-paths
larksuite__cli/shortcuts/sheets/data/flag-defs.json
T
zhengzhijiej-tech ea17864b52 docs(sheets): clarify dropdown values and default colors (#2582) 
* docs(sheets): clarify multi-select dropdown values

* docs(sheets): clarify dropdown values and default colors

* docs(sheets): address dropdown review feedback

* docs(sheets): document dropdown color readback
2026-09-01 19:28:56 +08:00

6049 lines
178 KiB
JSON
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
{
"+formula-verify": {
"risk": "read",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string_slice",
"required": "optional",
"desc": "Sheet reference_id(s); repeat or comma-separate to scan multiple sheets. Omit to scan all visible sheets."
},
{
"name": "sheet-name",
"kind": "public",
"type": "string_slice",
"required": "optional",
"desc": "Sheet name(s); repeat or comma-separate to scan multiple sheets. Omit to scan all visible sheets."
},
{
"name": "range",
"kind": "own",
"type": "string_slice",
"required": "optional",
"desc": "Optional A1 ranges (e.g. `A1:Z200`); repeat or comma-separate for multiple ranges. Omit to scan each sheet's current_region."
},
{
"name": "max-locations",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Max locations / samples per error type; default 20.",
"default": "20"
},
{
"name": "exit-on-error",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "When status=errors_found, exit non-zero. Useful for CI gate after batch formula writes."
},
{
"name": "ai-only",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Only verify AI formulas (=AI(prompt, [range])), skipping the 7 Excel-error scan of ordinary formulas. AI formulas compute asynchronously: use this flag with --range as the first post-write sample check, not cells-get polling; if the sample has no explicit failed/unsupported state, delivery may proceed with pending formulas while telling the user that computation continues in the background."
}
]
},
"+workbook-info": {
"risk": "read",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet locator"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet locator"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+sheet-list": {
"risk": "read",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet locator"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet locator"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+revision-get": {
"risk": "read",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet locator"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet locator"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+sheet-create": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "title",
"kind": "own",
"type": "string",
"required": "required",
"desc": "New sheet title"
},
{
"name": "index",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Insert position (0-based); appended to the end when omitted",
"default": "-1"
},
{
"name": "row-count",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Initial row count (default 200, max 50000)",
"default": "200"
},
{
"name": "col-count",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Initial column count (default 20, max 200)",
"default": "20"
},
{
"name": "type",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "New sub-sheet type: sheet (spreadsheet); default sheet.",
"default": "sheet",
"enum": [
"sheet"
]
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+sheet-delete": {
"risk": "high-risk-write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "yes",
"kind": "system",
"type": "bool",
"required": "required",
"desc": "Confirm high-risk write (exit code 10 without this flag)"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+sheet-rename": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "title",
"kind": "own",
"type": "string",
"required": "required",
"desc": "New title"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+sheet-move": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "index",
"kind": "own",
"type": "int",
"required": "required",
"desc": "Target position (0-based)"
},
{
"name": "source-index",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Source position (0-based); optional for standalone calls — if omitted, the CLI runtime derives it from the current workbook index of `--sheet-id` / `--sheet-name`. Inside `+batch-update` it must be passed explicitly, since batch cannot issue a structure query mid-run to derive it",
"default": "-1"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+sheet-copy": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "title",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Copy title; auto-generated by the server when omitted"
},
{
"name": "index",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Insert position for the copy (0-based); appended to the end when omitted",
"default": "-1"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+sheet-hide": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+sheet-unhide": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+sheet-set-tab-color": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "color",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Hex color like `#FF0000`; pass empty string `\"\"` to clear"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+sheet-hide-gridline": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+sheet-show-gridline": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+workbook-create": {
"risk": "write",
"flags": [
{
"name": "title",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Spreadsheet title"
},
{
"name": "folder-token",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Target folder token; placed at the drive root when omitted"
},
{
"name": "values",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Untyped initial data as one 2D JSON array (`[[\"alice\",95]]`); values are written as-is with their type auto-detected (dates / numbers land as text — use --sheets to preserve types), through the same batched set_cell_range path as --sheets — pair with --styles for number formats, colors, merges, and row/col sizes",
"input": [
"file",
"stdin"
]
},
{
"name": "sheets",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Typed table payload as JSON (same shape as `+table-put`): top-level `{\"sheets\":[...]}`, with each array item a sub-sheet `{name, start_cell?, mode?, header?, allow_overwrite?, columns:[\"colA\",\"colB\",...], data:[[...]], dtypes?:{colA:pandasDtype, ...}, formats?:{colA:numberFormat, ...}}` — `name` and the outer `sheets` envelope are both required. Agents typically use `df_to_sheet(df, name)` from `scripts/sheets_df.py` to pack each DataFrame into one item, then wrap the list in `{\"sheets\":[...]}`. Mutually exclusive with --values. Creates the workbook, then writes typed type-faithful data (dates land as real dates, numbers keep precision).",
"input": [
"file",
"stdin"
]
},
{
"name": "styles",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Initial visual operations as JSON: top-level `{styles:[...]}`. Each item corresponds to one target sheet and must include `name`, plus at least one of `cell_styles` / `row_sizes` / `col_sizes` / `cell_merges`. `cell_styles` entries use +cells-set-style fields with a cell range; row/col sizes use dimension ranges plus type/size; merges use cell ranges plus optional merge_type. With --sheets, styles array length/order/name must match --sheets.sheets. With --values, pass exactly one styles item for the initial sheet (its name is ignored).",
"input": [
"file",
"stdin"
]
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+workbook-export": {
"risk": "read",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "file-extension",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Export file format; `csv` mode requires `--sheet-id`",
"default": "xlsx",
"enum": [
"xlsx",
"csv"
]
},
{
"name": "sheet-id",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Required only in csv mode: which sheet to export as CSV. This is a `+workbook-export`-specific flag, unrelated to the common four-tuple sheet locator (this shortcut does not accept the common sheet locator)"
},
{
"name": "output-path",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Local save path. When omitted, **only the export task is triggered + polled, the file is NOT downloaded** (returns file_token / status so a later step can resume the download). Pass a concrete path (e.g. `./out.xlsx`) or a directory (`.` keeps the server-provided filename) to download. Note: the equivalent `lark-cli drive +export --doc-type sheet` uses three separate flags (`--output-dir` / `--file-name` / `--overwrite`) and defaults to downloading into the current directory; this wrapper collapses them into a single `--output-path` for ergonomics but defaults to no-download — fall back to `drive +export` if the split flag set fits better."
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+workbook-import": {
"risk": "write",
"flags": [
{
"name": "file",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Local file path (.xlsx / .xls / .csv)"
},
{
"name": "folder-token",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Target folder token; imported to the cloud drive root when omitted"
},
{
"name": "name",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Imported spreadsheet name; defaults to the local file name without its extension"
}
]
},
"+sheet-info": {
"risk": "read",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "include",
"kind": "own",
"type": "string_slice",
"required": "optional",
"desc": "Comma-separated structure info categories to return",
"enum": [
"merges",
"row_heights",
"col_widths",
"hidden_rows",
"hidden_cols",
"groups",
"frozen"
]
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Limit structure info to this A1 range; whole sheet when omitted"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+dim-insert": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "inherit-style",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Style inheritance for the new row/column: `before` (from the preceding row/column) / `after` (from the following row/column). Omit the flag to inherit the following row/column (same as `after`) — the backend cannot leave a new row/column unstyled; for a truly blank row/column, clear formats afterwards with +cells-clear --scope formats. Insertion always lands before `--position`; this only selects which side's style is copied.",
"enum": [
"before",
"after"
]
},
{
"name": "position",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Insert position (1-based row number like `3` or column letter like `C`); new rows/columns are inserted *before* this position"
},
{
"name": "count",
"kind": "own",
"type": "int",
"required": "required",
"desc": "Number of rows/columns to insert (must be > 0)"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+dim-delete": {
"risk": "high-risk-write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "xor",
"desc": "Row/column closed range to delete; rows use 1-based numbers like `3:7` or `5` (single row), columns use letters like `C:F` or `C`. XOR with `--ranges`"
},
{
"name": "ranges",
"kind": "own",
"type": "string",
"required": "xor",
"desc": "Multiple row/column ranges to delete as a JSON array (up to 100 items, e.g. `[\"5:5\",\"8:8\",\"11:13\"]` or `[\"C:C\",\"F:G\"]`); rows and columns cannot be mixed, ranges must not overlap; XOR with `--range`. CLI sorts positions in DESCENDING order into one batched delete (fail-fast; read back before resending) — ascending deletion would shift later indexes as earlier rows/columns disappear; the CLI handles the ordering",
"input": [
"file",
"stdin"
]
},
{
"name": "yes",
"kind": "system",
"type": "bool",
"required": "required",
"desc": "Confirm destructive write (exit code 10 without this flag); row/column deletion is irreversible"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+dim-hide": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Row/column closed range to hide; rows use 1-based numbers like `3:7`, columns use letters like `C:F`"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+dim-unhide": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Row/column closed range to unhide; rows use 1-based numbers like `3:7`, columns use letters like `C:F`"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+dim-freeze": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "dimension",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "[legacy] Dimension (row or column), paired with --count; sets one axis only and unfreezes the other. Prefer --rows / --cols",
"hidden": true,
"enum": [
"row",
"column"
]
},
{
"name": "count",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "[legacy] Freeze the first N rows/columns (paired with --dimension); 0 clears all freezing. Equivalent to --rows N / --cols N, and only --rows/--cols can hold both axes at once",
"hidden": true
},
{
"name": "rows",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Freeze the first N rows; together with --cols this states the COMPLETE freeze state — an omitted axis is left unfrozen (0 means no frozen rows)"
},
{
"name": "cols",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Freeze the first N columns; together with --rows this states the COMPLETE freeze state — an omitted axis is left unfrozen (0 means no frozen columns)"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+dim-group": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "depth",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Nesting level for grouping; default 1",
"default": "1"
},
{
"name": "group-state",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Initial group expand state",
"default": "expand",
"enum": [
"expand",
"fold"
]
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Row/column closed range to group; rows use 1-based numbers like `3:7`, columns use letters like `C:F`"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+dim-ungroup": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "depth",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Group nesting level to ungroup; default 1 (1 = outermost, larger = deeper)",
"default": "1"
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Row/column closed range to ungroup; rows use 1-based numbers like `3:7`, columns use letters like `C:F`"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+dim-move": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "source-range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Source row/column closed range to move; rows use 1-based numbers like `3:7`, columns use letters like `C:F`"
},
{
"name": "target",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Destination position (the moved rows/columns are placed *before* this position); rows use 1-based row number like `12`, columns use column letter like `H`. Must match the dimension of --source-range"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+cells-get": {
"risk": "read",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "A1 range, e.g. `A1:F10` (no sheet prefix — use `--sheet-id` / `--sheet-name` to select the sheet)"
},
{
"name": "include",
"kind": "own",
"type": "string_slice",
"required": "optional",
"desc": "Comma-separated info categories to include. `truncation` additionally estimates whether each cell's content is clipped (by row height / col width / font size / wrap) and returns `isRowTruncated` / `isColTruncated` (extra compute; enable only for layout checks or before adjusting row heights / column widths)",
"enum": [
"value",
"formula",
"style",
"comment",
"data_validation",
"conditional_format",
"truncation"
]
},
{
"name": "max-chars",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Max output chars per call; default 500000 (safety cap). For a full untruncated read, use --output-path to dump to a file (the cap auto-raises to a bounded 20M chars — the read path is not streaming, this cap is the memory guard; pass an explicit --max-chars for more); only lower it (e.g. 25000) when you want results inline without a file, paging via has_more. Passing 0 means \"no cap of my own\" and resolves to the same ceiling as leaving the flag alone (500000, or the offload limit with --output-path) — never down to the tool's smaller omitted-value fallback.",
"default": "500000"
},
{
"name": "output-path",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Write the full read result to a local path (e.g. `./out.json`); the file holds the data payload as JSON while stdout returns only a small confirmation (output_path, byte count). **When set, the char cap auto-raises to a bounded offload default (20M chars)** rather than unlimited — the read path is not streaming, so this cap is the memory guard; an explicit --max-chars overrides it. The stdout receipt reports `complete` (and `truncated` plus a warning when the cap was hit), so check it instead of assuming the file holds the whole sheet. Omit it to print to stdout as usual."
},
{
"name": "skip-hidden",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Skip hidden rows and columns; default `false`"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+dropdown-get": {
"risk": "read",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Target range in A1 notation, e.g. `A2:A100` (no sheet prefix — use `--sheet-id` / `--sheet-name` to select the sheet)"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+csv-get": {
"risk": "read",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "A1 range, e.g. `A1:F30` (no sheet prefix — use `--sheet-id` / `--sheet-name` to select the sheet). Optional: when omitted the whole sheet is read (clipped to the actual grid bounds; actual_range in the response names what was read); pair with --max-chars / --output-path on large sheets"
},
{
"name": "max-chars",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Max output chars per call; default 500000 (safety cap). For a full untruncated read, use --output-path to dump to a file (the cap auto-raises to a bounded 20M chars — the read path is not streaming, this cap is the memory guard; pass an explicit --max-chars for more); only lower it (e.g. 25000) when you want results inline without a file, paging via has_more. Passing 0 means \"no cap of my own\" and resolves to the same ceiling as leaving the flag alone (500000, or the offload limit with --output-path) — never down to the tool's smaller omitted-value fallback.",
"default": "500000"
},
{
"name": "output-path",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Write the full read result to a local path (e.g. `./out.json`); the file holds the data payload as JSON while stdout returns only a small confirmation (output_path, byte count). **When set, the char cap auto-raises to a bounded offload default (20M chars)** rather than unlimited — the read path is not streaming, so this cap is the memory guard; an explicit --max-chars overrides it. The stdout receipt reports `complete` (and `truncated` plus a warning when the cap was hit), so check it instead of assuming the file holds the whole sheet. Note the file is the data payload as JSON — on +csv-get too, where the CSV text sits in a field inside it — not a ready-to-use .csv; redirect stdout instead if you want a bare CSV file. Omit it to print to stdout as usual."
},
{
"name": "include-row-prefix",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Whether to prefix each row with `[row=N]`; default `true`",
"default": "true"
},
{
"name": "skip-hidden",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Skip hidden rows and columns; default `false`"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": "Print the request path and parameters without executing"
}
]
},
"+table-get": {
"risk": "read",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Read only this sheet (by id); omit to read all sheets"
},
{
"name": "sheet-name",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Read only this sheet (by name); omit to read all sheets"
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "A1 range to read; omit to read each sheet's full used range (spans internal blank rows/columns, not just the A1 current region)"
},
{
"name": "max-chars",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Max output chars per call; default 500000 (safety cap). The underlying tool truncates at ~50000 even when unset, so this is sent explicitly to raise it; for a full untruncated read use --output-path (cap auto-raises to a bounded 20M chars; explicit --max-chars overrides). Passing 0 means \"no cap of my own\" and resolves to the same ceiling as leaving the flag alone (500000, or the offload limit with --output-path) — never down to the tool's smaller omitted-value fallback.",
"default": "500000"
},
{
"name": "output-path",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Write the full read result to a local path (e.g. `./out.json`); the file holds the data payload as JSON while stdout returns only a small confirmation (output_path, byte count). **When set, the char cap auto-raises to a bounded offload default (20M chars)** rather than unlimited — the read path is not streaming, so this cap is the memory guard; an explicit --max-chars overrides it. The stdout receipt reports `complete` (and `truncated` plus a warning when the cap was hit), so check it instead of assuming the file holds the whole sheet. Omit it to print to stdout as usual."
},
{
"name": "no-header",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Treat the first row as data instead of a header (columns get positional names col1, col2, ...)"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+cells-search": {
"risk": "read",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "find",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Text to find (interpreted as regex when `--regex` is set)"
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Search range (A1 notation); whole sheet when omitted"
},
{
"name": "match-case",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Case-sensitive match"
},
{
"name": "match-entire-cell",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Match the entire cell content"
},
{
"name": "regex",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Interpret `--find` as a regex pattern"
},
{
"name": "include-formulas",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Also search within formula text"
},
{
"name": "max-matches",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Safety cap; default 5000",
"default": "5000",
"hidden": true
},
{
"name": "offset",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Skip the first N matches (for pagination); default 0",
"default": "0"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+cells-replace": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "find",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Text to find for replacement"
},
{
"name": "replacement",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Replacement text; pass empty string `\"\"` to delete matched content"
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Replace range (A1 notation); whole sheet when omitted"
},
{
"name": "match-case",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Case-sensitive match"
},
{
"name": "match-entire-cell",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Match the entire cell content"
},
{
"name": "regex",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Interpret `--find` as a regex pattern"
},
{
"name": "include-formulas",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Also replace within formula text"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": "Required preflight: outputs `would_replace_count` for user confirmation before the actual replace"
}
]
},
"+cells-set": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two); not accepted with `--writes` (each writes item carries its own sheet selector)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two); not accepted with `--writes` (each writes item carries its own sheet selector)"
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "xor",
"desc": "Write range (A1 notation). XOR with `--writes` (single region: --range+--cells; multiple regions: --writes)"
},
{
"name": "cells",
"kind": "own",
"type": "string",
"required": "xor",
"desc": "JSON 2D array `[[{cell},...],...]`, dimensions must match `--range`; each cell may carry `value` / `formula` / `multiple_values` / `cell_styles` / `note` / `rich_text` (incl. `type=\"embed-image\"` in-cell image). To write selected values into a multi-select dropdown cell, use `multiple_values:[{\"value\":...}]`; do not join multiple options with commas into one `value`. Run `--print-schema` for full fields",
"input": [
"file",
"stdin"
]
},
{
"name": "writes",
"kind": "own",
"type": "string",
"required": "xor",
"desc": "Multi-region write as a JSON array (up to 100 items), each `{sheet_name|sheet_id, range, cells}` — the sheet selector LIVES IN EACH ITEM (same convention as +batch-update sub-ops and +styles-put items; the top-level --sheet-name is rejected). cells has the same shape as `--cells` (2D array; per-cell cell_styles/border_styles allowed). The whole array goes out as ONE batched request (fail-fast; read back to confirm what applied before resending), cross-sheet supported; typical use: fixing formulas scattered across ranges/sheets — do not assemble a +batch-update operations array for this. XOR with `--range`+`--cells`; range-level uniform styling stays with +styles-put afterwards",
"input": [
"file",
"stdin"
]
},
{
"name": "allow-overwrite",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Allow overwriting non-empty cells (default true); set false to error if any target cell is non-empty",
"default": "true"
},
{
"name": "max-cells",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Safety cap; default 50000",
"default": "50000",
"hidden": true
},
{
"name": "copy-to-range",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Copy-to range (A1 notation): replicate what --cells wrote into --range (values/formulas/styles, per the fields actually passed) to this range; formula refs auto-shift (C2=B2 -> C3=B3). Write a one-row/one-block template then fill a whole column/area. Supports full rows '3:6', full columns 'C:E', to-col-end 'D3:D', to-row-end 'D3:3', and comma-separated multiple targets like 'C1:D2,E5:F6'."
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+cells-set-style": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Target range (A1 notation, e.g. `A1:B2`)"
},
{
"name": "background-color",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Background color (hex, e.g. `#ffffff`)"
},
{
"name": "font-color",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Font color (hex, e.g. `#000000`)"
},
{
"name": "font-family",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Font family name (e.g. `Arial`, `Microsoft YaHei`)"
},
{
"name": "font-size",
"kind": "own",
"type": "float64",
"required": "optional",
"desc": "Font size in px (e.g. 10, 12, 14)"
},
{
"name": "font-style",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Font style",
"enum": [
"normal",
"italic"
]
},
{
"name": "font-weight",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Font weight",
"enum": [
"normal",
"bold"
]
},
{
"name": "font-line",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Font line style",
"enum": [
"none",
"underline",
"line-through"
]
},
{
"name": "horizontal-alignment",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Horizontal alignment",
"enum": [
"left",
"center",
"right"
]
},
{
"name": "vertical-alignment",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Vertical alignment",
"enum": [
"top",
"middle",
"bottom"
]
},
{
"name": "word-wrap",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Word-wrap strategy",
"enum": [
"overflow",
"auto-wrap",
"word-clip"
]
},
{
"name": "number-format",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Number format pattern (e.g. text `@`, number `0.00`, currency `$#,##0.00`, date `mm/dd/yyyy`)"
},
{
"name": "border-styles",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Border config JSON: `{ top: {style,weight,color}, bottom: ..., left: ..., right: ... }`; same shape for all 4 sides. style = line type (solid|dashed|dotted|double|none); weight = thickness (thin|medium|thick — a string, not a pixel number); color = hex like #000000. { all: {...} } sets all four sides at once. This is the only border flag: no --border-all / --border-top / --border-color exist",
"input": [
"file",
"stdin"
]
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+cells-set-image": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Target cell (A1 notation; must be a single cell, e.g. `A1`; start and end must be identical)"
},
{
"name": "image",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Local image path (PNG / JPEG / JPG / GIF / BMP / JFIF / EXIF / TIFF / BPG / HEIC)"
},
{
"name": "name",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Image file name (with extension); defaults to the basename of `--image`"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+dropdown-set": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Target range (A1 notation, e.g. `A2:A100`)"
},
{
"name": "options",
"kind": "own",
"type": "string",
"required": "xor",
"desc": "Options as a JSON array, e.g. `[\"opt1\",\"opt2\"]`. Server enforces no item-count cap and no per-item length cap; values containing commas are accepted (they are escape-encoded on the wire). For very large lists prefer `--source-range`.",
"input": [
"file",
"stdin"
]
},
{
"name": "colors",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Per-option pill background colors as an RGB hex array. Omit when creating a dropdown to use the built-in 10-color palette; pass only when the user explicitly requests custom colors or options have clear color semantics. Pill text is black, so prefer light, low-saturation backgrounds. The array may be shorter than the source (`--options` items / `--source-range` cells) — extras use the built-in palette — but never longer (CLI Validate rejects: `--colors length (N) must not exceed dropdown source size (M)`). Applies on its own; ignored when `--highlight=false`.",
"input": [
"file",
"stdin"
]
},
{
"name": "multiple",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Enable multi-select; default `false`. This flag only configures validation and does not write selected values. When writing selections with `+cells-set`, pass a `multiple_values` array, not a comma-joined `value`"
},
{
"name": "highlight",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Pill-highlight switch. **Omitted = ON** (options cycle through a 10-color palette). Pass `--highlight=false` for a plain dropdown. Override colors via `--colors`."
},
{
"name": "source-range",
"kind": "own",
"type": "string",
"required": "xor",
"desc": "Source range for listFromRange dropdown (A1 + sheet prefix, e.g. `'Sheet1'!T1:T3`); maps to server `data_validation.range` and auto-sets `data_validation.type='listFromRange'`. XOR with `--options`: pass `--options` for an inline list (type=list), pass this for a range reference (type=listFromRange). `--colors` length rule unchanged (≤ source range cell count); `--highlight` / `--multiple` behave the same. When `--highlight` is on and the source covers more than 2000 cells, the server flags the dropdown as option-error (highlight + large source is an unsupported combo); CLI reports the warning in the result's `data.warnings`. Pass `--highlight=false` to suppress."
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+csv-put": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "start-cell",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Top-left A1 anchor (e.g. `A1`, `B5`; no sheet prefix — use `--sheet-id` / `--sheet-name` to select the sheet); must be a single cell, range notation not accepted; the bottom-right is inferred from CSV row/column counts",
"default": "A1"
},
{
"name": "csv",
"kind": "own",
"type": "string",
"required": "required",
"desc": "RFC 4180 CSV text; values or formulas (a leading = is evaluated as a formula); no styles / comments / images (use +cells-set for those).",
"input": [
"file",
"stdin"
]
},
{
"name": "allow-overwrite",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Allow overwriting (default true); set false to error if any target cell is non-empty",
"default": "true"
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "alias for --start-cell (parity with +csv-get / +cells-set, which locate with --range); a range like A1:H17 collapses to its top-left cell",
"hidden": true
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+table-put": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL to write into (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token to write into (XOR with `--url`)"
},
{
"name": "sheets",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Typed table payload (pandas-DataFrame-shaped) as JSON: top-level `{\"sheets\":[...]}`, with each array item a sub-sheet `{name, start_cell?, mode?, header?, allow_overwrite?, columns:[\"colA\",\"colB\",...], data:[[...]], dtypes?:{colA:pandasDtype, ...}, formats?:{colA:numberFormat, ...}}` — `name` and the outer `sheets` envelope are both required. Agents typically use `df_to_sheet(df, name)` from `scripts/sheets_df.py` to pack each DataFrame into one item, then wrap the list in `{\"sheets\":[...]}`. `dtypes` values are pandas dtype strings (`int64`, `float64`, `Int64`, `bool`, `boolean`, `datetime64[ns]`, `object`, ...); the writer maps them to internal string/number/date/bool — omit `dtypes` and a column writes as text (good for raw CSV-shaped data). `formats[col]` is an Excel number_format string (e.g. `#,##0.00`, `0.0%`, `yyyy-mm`); when absent, date columns default to `yyyy-mm-dd` and string columns to text format (`@`).",
"input": [
"file",
"stdin"
]
},
{
"name": "styles",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Visual operations applied after the typed write, as JSON: top-level `{styles:[...]}`. Each item corresponds to one written sheet and must include `name`, plus at least one of `cell_styles` / `row_sizes` / `col_sizes` / `cell_merges`. `cell_styles` entries use +cells-set-style fields with a cell range; row/col sizes use dimension ranges plus type/size; merges use cell ranges plus optional merge_type. The styles array length/order/name must match the written sheets in --sheets.sheets. Run `+table-put --print-schema --flag-name styles` for the full cell_styles field schema.",
"input": [
"file",
"stdin"
]
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+cells-clear": {
"risk": "high-risk-write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Range to clear (A1 notation)"
},
{
"name": "scope",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Clear scope: `content` (default, values only) / `formats` (formats only) / `all` (values and formats)",
"default": "content",
"enum": [
"content",
"formats",
"all"
]
},
{
"name": "yes",
"kind": "system",
"type": "bool",
"required": "required",
"desc": "Confirm destructive write (exit code 10 without this flag); clear is irreversible"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+cells-merge": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Range to merge / unmerge (A1 notation)"
},
{
"name": "merge-type",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Merge direction (`+cells-merge` only)",
"default": "all",
"enum": [
"all",
"rows",
"columns"
]
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+cells-unmerge": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Range to merge / unmerge (A1 notation)"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+rows-resize": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "height",
"kind": "own",
"type": "int",
"required": "xor",
"desc": "Uniform row height in pixels (e.g. 30 / 40 / 60; NOT points), used with `--range`. Passing --height implies pixel mode; --type may be omitted (or set to `pixel` — equivalent). For per-row heights use `--heights`",
"default": "0"
},
{
"name": "heights",
"kind": "own",
"type": "string",
"required": "xor",
"desc": "Per-row height map — set different heights for many rows in one batched call (fail-fast; read back before resending). Keys: single row (`\"1\"`) or closed range (`\"2:20\"`); values: pixel height (e.g. 30 / 50), `\"auto\"` (fit content) or `\"standard\"` (reset to default). Units are pixels, NOT points. Mutually exclusive with `--range` / `--height` / `--type`",
"input": [
"file",
"stdin"
]
},
{
"name": "type",
"kind": "own",
"type": "string",
"required": "xor",
"desc": "Sizing mode: `pixel` (requires `--height`) / `standard` (reset to default row height) / `auto` (fit content). Passing --height alone is the common form; `--type standard` / `--type auto` cannot be combined with `--height`",
"enum": [
"pixel",
"standard",
"auto"
]
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "xor",
"desc": "Row closed range to resize; 1-based row numbers like `2:10` or `5` (single row). Required for the uniform form (with `--height` or `--type`); omit with the map form (`--heights`)"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+cols-resize": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "width",
"kind": "own",
"type": "int",
"required": "xor",
"desc": "Uniform column width in pixels (e.g. 80 / 120 / 200; NOT Excel character units), used with `--range`. Passing --width implies pixel mode; --type may be omitted (or set to `pixel` — equivalent). For per-column widths use `--widths`",
"default": "0"
},
{
"name": "widths",
"kind": "own",
"type": "string",
"required": "xor",
"desc": "Per-column width map — set different widths for many columns in one batched call (fail-fast; read back before resending). Keys: single column (`\"A\"`) or closed range (`\"C:E\"`); values: pixel width (e.g. 80 / 120 / 200) or `\"standard\"` (reset to default). Units are pixels, NOT Excel character units (px ≈ chars × 8 + 16). Mutually exclusive with `--range` / `--width` / `--type`",
"input": [
"file",
"stdin"
]
},
{
"name": "type",
"kind": "own",
"type": "string",
"required": "xor",
"desc": "Sizing mode: `pixel` (requires `--width`) / `standard` (reset to default column width). Passing --width alone is the common form; `--type standard` cannot be combined with `--width`",
"enum": [
"pixel",
"standard"
]
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "xor",
"desc": "Column closed range to resize; column letters like `A:E` or `C` (single column). Required for the uniform form (with `--width` or `--type`); omit with the map form (`--widths`)"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+range-move": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "source-range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Source A1 range"
},
{
"name": "target-sheet-id",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Destination sub-sheet id; defaults to the same sheet as the source"
},
{
"name": "target-range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Destination A1 range (anchor cell is enough; size inferred from the source)"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+range-copy": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "source-range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Source A1 range"
},
{
"name": "target-sheet-id",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Destination sub-sheet id; defaults to the same sheet as the source"
},
{
"name": "target-range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Destination A1 range (anchor cell is enough; size inferred from the source)"
},
{
"name": "paste-type",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Paste content type (`+range-copy` only)",
"default": "all",
"enum": [
"values",
"formulas",
"formats",
"all"
]
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+range-fill": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "source-range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Fill template range (seed cells for the series)"
},
{
"name": "target-range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Destination fill range (A1 notation)"
},
{
"name": "series-type",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Fill series type",
"default": "auto",
"enum": [
"auto",
"linear",
"growth",
"date",
"copy"
]
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+range-sort": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Sort range (A1 notation; whether the header is included depends on `--has-header`)"
},
{
"name": "sort-keys",
"kind": "own",
"type": "string",
"required": "required",
"desc": "JSON array: `[{\"column\":\"<col letter>\",\"ascending\":<bool>}, ...]`",
"input": [
"file",
"stdin"
]
},
{
"name": "has-header",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Treat the first row as a header and exclude from sort; default `false`"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+styles-put": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet locator (target sheets are named inside --styles items)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "styles",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Visual spec JSON applied to an EXISTING spreadsheet: top-level `{styles:[...]}`, one item per target sheet (`name` is the real sheet name), each giving at least one of `cell_styles` / `cell_merges` / `row_sizes` / `col_sizes` / `freeze`. The vocabulary is identical to `--styles` on `+workbook-create` / `+table-put` (cell_styles = A1 range + flat style fields, borders via the `border` shorthand {style,weight,color} applied to all four sides — border_styles only for per-side differences; row/col sizes = row/column range + size in px — type only for standard/auto; merges = cell range; freeze = `{rows:N, cols:N}`). The whole spec expands into one batched request (fail-fast: do not assume what applied — read back to confirm before resending); ranges may target any region of the sheet",
"input": [
"file",
"stdin"
]
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": "Print the batched request template for each expanded operation; no network side effects"
}
]
},
"+batch-update": {
"risk": "high-risk-write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet locator (independent from per-operation sheet locator)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet locator (independent from per-operation sheet locator)"
},
{
"name": "operations",
"kind": "own",
"type": "string",
"required": "required",
"desc": "JSON array: [{\"shortcut\":\"+xxx-yyy\",\"input\":{...}}, ...]. shortcut uses CLI names; input is that shortcut's flag set — it includes the per-operation sheet locator (sheet_id or sheet_name) but not the spreadsheet token/url (pass that once at the top level via --url/--spreadsheet-token; +batch-update has no top-level --sheet-id). input keys are the shortcut's flags flattened into JSON (e.g. \"range\":\"A11:B12\"), not another nested layer. For basic flags use lark-cli sheets <shortcut> --help; for composite JSON flags use --print-schema --flag-name <flag>. Do not pass an explicit operation field. Fail-fast by default: the first failure aborts the remaining operations. Whether earlier sub-operations persisted is NOT uniform: pure cell/structure writes are only buffered and are dropped on failure (effective rollback), while chart/pivot-type sub-operations flush the buffered writes to disk before creating the object and cannot be rolled back. After a failure, assume neither full-rollback nor full-persist — check results, read back the current state (dims / target cells / object lists) to determine what actually applied, then resend only the unapplied part. Pass --continue-on-error to keep going past failures with successes preserved; no nesting; executed serially.",
"input": [
"file",
"stdin"
]
},
{
"name": "continue-on-error",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Continue with remaining operations when a sub-operation fails; default false (abort on first failure)"
},
{
"name": "yes",
"kind": "system",
"type": "bool",
"required": "required",
"desc": "Confirm high-risk write (exit code 10 without this flag)"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": "Print the request template for each sub-operation; no network side effects"
}
]
},
"+batch-chart-create": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "operations",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Chart creation operations as JSON; put each target sheet selector and `+chart-create-basic` flag directly on the item, without `shortcut` or `input`. The CLI dispatches every item through `+chart-create-basic` internally. Partial failure is enabled by default: successful charts stay applied and only failed items should be retried",
"input": [
"file",
"stdin"
]
},
{
"name": "continue-on-error",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Continue after an individual chart fails; default true",
"default": "true"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": "Print the internal MCP request template with no network side effects; tool_name / operation / basic_chart in the output are for inspection only and must not be copied back into --operations"
}
]
},
"+batch-chart-update": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "operations",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Chart update operations as JSON; every item uses `+chart-config-update` or `+chart-data-update`, with that command's flags and target sheet selector in input. The CLI reads each current chart snapshot before building partial properties; partial failure is enabled by default",
"input": [
"file",
"stdin"
]
},
{
"name": "continue-on-error",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Continue after an individual chart fails; default true",
"default": "true"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": "Print the batch update request template and snapshot preflight note with no network side effects"
}
]
},
"+cells-batch-set-style": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "ranges",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Target ranges as a JSON array (up to 100 items, e.g. `[\"Sheet1!A1:B2\",\"Sheet2!D1:D10\"]`, prefix written bare without quotes); each prefix must exactly match the sheet display name (case-sensitive), not the sheet reference_id; ranges may target different sheets; the same style is applied to every range",
"input": [
"file",
"stdin"
]
},
{
"name": "background-color",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Background color (hex, e.g. `#ffffff`)"
},
{
"name": "font-color",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Font color (hex, e.g. `#000000`)"
},
{
"name": "font-family",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Font family name (e.g. `Arial`, `Microsoft YaHei`)"
},
{
"name": "font-size",
"kind": "own",
"type": "float64",
"required": "optional",
"desc": "Font size in px (e.g. 10, 12, 14)"
},
{
"name": "font-style",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Font style",
"enum": [
"normal",
"italic"
]
},
{
"name": "font-weight",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Font weight",
"enum": [
"normal",
"bold"
]
},
{
"name": "font-line",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Font line style",
"enum": [
"none",
"underline",
"line-through"
]
},
{
"name": "horizontal-alignment",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Horizontal alignment",
"enum": [
"left",
"center",
"right"
]
},
{
"name": "vertical-alignment",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Vertical alignment",
"enum": [
"top",
"middle",
"bottom"
]
},
{
"name": "word-wrap",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Word-wrap strategy",
"enum": [
"overflow",
"auto-wrap",
"word-clip"
]
},
{
"name": "number-format",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Number format pattern (e.g. text `@`, number `0.00`, currency `$#,##0.00`, date `mm/dd/yyyy`)"
},
{
"name": "border-styles",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Border config JSON (same shape as in +cells-set-style): `{ top|bottom|left|right|all: {style,weight,color} }`; style = solid|dashed|dotted|double|none, weight = thin|medium|thick (string), color = hex like #000000",
"input": [
"file",
"stdin"
]
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+dropdown-update": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "ranges",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Target ranges as a JSON array (up to 100 items, e.g. `[\"Sheet1!A2:A100\",\"Sheet1!C2:C100\"]`, prefix written bare without quotes); each item must include a sheet prefix; the prefix must exactly match the sheet display name (case-sensitive), not the sheet reference_id",
"input": [
"file",
"stdin"
]
},
{
"name": "options",
"kind": "own",
"type": "string",
"required": "xor",
"desc": "Options as a JSON array, e.g. `[\"opt1\",\"opt2\"]`. Server enforces no item-count cap and no per-item length cap; values containing commas are accepted (they are escape-encoded on the wire). For very large lists prefer `--source-range`.",
"input": [
"file",
"stdin"
]
},
{
"name": "colors",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Per-option pill background colors as an RGB hex array. Updating rewrites the entire validation rule: unless the user asks to reset colors, first read the dropdown with `+dropdown-get` and pass its existing `highlight_colors` through this flag; omission rebuilds colors from the built-in 10-color palette. For explicitly requested or semantic new colors, prefer light, low-saturation backgrounds because pill text is black. The array may be shorter than the source (`--options` items / `--source-range` cells) — extras use the built-in palette — but never longer (CLI Validate rejects: `--colors length (N) must not exceed dropdown source size (M)`). Applies on its own; ignored when `--highlight=false`.",
"input": [
"file",
"stdin"
]
},
{
"name": "multiple",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Enable multi-select. This flag only updates validation and does not write selected values. When writing selections with `+cells-set`, pass a `multiple_values` array, not a comma-joined `value`"
},
{
"name": "highlight",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Pill-highlight switch. **Omitted = ON** (options cycle through a 10-color palette). Pass `--highlight=false` for a plain dropdown. Override colors via `--colors`."
},
{
"name": "source-range",
"kind": "own",
"type": "string",
"required": "xor",
"desc": "Source range for listFromRange dropdown (A1 + sheet prefix, e.g. `'Sheet1'!T1:T3`); maps to server `data_validation.range` and auto-sets `data_validation.type='listFromRange'`. XOR with `--options`: pass `--options` for an inline list (type=list), pass this for a range reference (type=listFromRange). `--colors` length rule unchanged (≤ source range cell count); `--highlight` / `--multiple` behave the same. When `--highlight` is on and the source covers more than 2000 cells, the server flags the dropdown as option-error (highlight + large source is an unsupported combo); CLI reports the warning in the result's `data.warnings`. Pass `--highlight=false` to suppress."
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+dropdown-delete": {
"risk": "high-risk-write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "ranges",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Target ranges as a JSON array (up to 100 items, e.g. `[\"Sheet1!E2:E6\"]`, prefix written bare without quotes); each item must include a sheet prefix; the prefix must exactly match the sheet display name (case-sensitive), not the sheet reference_id",
"input": [
"file",
"stdin"
]
},
{
"name": "yes",
"kind": "system",
"type": "bool",
"required": "required",
"desc": "Confirm high-risk write (exit code 10 without this flag)"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+cells-batch-clear": {
"risk": "high-risk-write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "ranges",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Target ranges as a JSON array (up to 100 items, e.g. `[\"Sheet1!A2:Z1000\",\"Sheet2!A2:Z1000\"]`, prefix written bare without quotes); each prefix must exactly match the sheet display name (case-sensitive), not the sheet reference_id; ranges may target different sheets; the same scope is cleared from every range",
"input": [
"file",
"stdin"
]
},
{
"name": "scope",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Clear scope: `content` (default, values only) / `formats` (formats only) / `all` (values and formats)",
"default": "content",
"enum": [
"content",
"formats",
"all"
]
},
{
"name": "yes",
"kind": "system",
"type": "bool",
"required": "required",
"desc": "Confirm destructive write (exit code 10 without this flag); batch clear is irreversible"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+chart-list": {
"risk": "read",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "chart-id",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Filter to a single chart reference_id"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+chart-create-basic": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id (XOR with `--sheet-name`)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name (XOR with `--sheet-id`)"
},
{
"name": "chart-type",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Chart type",
"enum": [
"column",
"bar",
"line",
"area",
"pie",
"scatter",
"combo",
"radar",
"bubble",
"waterfall",
"pareto"
]
},
{
"name": "data-range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Data range; include headers unless --header-range is set, in which case pass data only; accepts comma-separated ranges across one or more sheets"
},
{
"name": "header-range",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Optional detached header range; use one row for column direction or one column for row direction, with one header per data dimension"
},
{
"name": "data-direction",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Data series direction; column uses the first column as categories, row uses the first row",
"default": "column",
"enum": [
"column",
"row"
]
},
{
"name": "x-axis-numbers-as",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "How to interpret numeric X-axis values; text treats numbers as evenly spaced text categories, while values uses a continuous numeric scale and preserves true spacing",
"default": "text",
"enum": [
"text",
"values"
]
},
{
"name": "x-axis-min",
"kind": "own",
"type": "float64",
"required": "optional",
"desc": "Lower display bound for a continuous numeric X-axis; requires --x-axis-numbers-as values"
},
{
"name": "x-axis-max",
"kind": "own",
"type": "float64",
"required": "optional",
"desc": "Upper display bound for a continuous numeric X-axis; requires --x-axis-numbers-as values"
},
{
"name": "y-axis-min",
"kind": "own",
"type": "float64",
"required": "optional",
"desc": "Lower display bound for the left Y-axis; must be less than --y-axis-max"
},
{
"name": "y-axis-max",
"kind": "own",
"type": "float64",
"required": "optional",
"desc": "Upper display bound for the left Y-axis; must be greater than --y-axis-min"
},
{
"name": "dim1-index",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "1-based category/X-axis dimension index within the data range; defaults to 1"
},
{
"name": "dim2-indexes",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Comma-separated 1-based value/Y-axis dimension indexes; must exclude dim1, at most 50. Legacy bubble calls accept 2–4 indexes in `x,y[,group][,size]` order; new calls should use role-specific indexes. Pie and pareto charts accept exactly one"
},
{
"name": "series-types",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Combo charts only; comma-separated series types aligned with --dim2-indexes; use column, line, or area and provide one value per selected series"
},
{
"name": "series-y-axes",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Combo charts only; comma-separated left or right Y-axis assignments aligned with --dim2-indexes; provide one value per selected series"
},
{
"name": "key-index",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Bubble only: 1-based key/name dimension index; mutually exclusive with dim1/dim2 indexes; defaults to 1"
},
{
"name": "x-index",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Bubble only: 1-based X-value dimension index; must be provided with --y-index"
},
{
"name": "y-index",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Bubble only: 1-based Y-value dimension index; must be provided with --x-index"
},
{
"name": "group-index",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Bubble only: optional 1-based group dimension index"
},
{
"name": "size-index",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Bubble only: optional 1-based bubble-size dimension index"
},
{
"name": "title",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Chart title"
},
{
"name": "subtitle",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Chart subtitle"
},
{
"name": "legend-position",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Legend position; hidden removes the legend",
"enum": [
"top",
"bottom",
"left",
"right",
"hidden"
]
},
{
"name": "x-axis-title",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "X-axis title"
},
{
"name": "y-axis-title",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Left Y-axis title"
},
{
"name": "secondary-y-axis-title",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Right Y-axis title"
},
{
"name": "x-axis-label-angle",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "X-axis label angle",
"enum": [
"-90",
"-45",
"0",
"45",
"90"
]
},
{
"name": "y-axis-label-angle",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Left Y-axis label angle",
"enum": [
"-90",
"-45",
"0",
"45",
"90"
]
},
{
"name": "data-labels",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Data label content; combine value, category, and percentage in value_category_percentage order for any non-empty combination; series shows series names and none removes labels",
"enum": [
"none",
"value",
"category",
"percentage",
"value_category",
"value_percentage",
"category_percentage",
"value_category_percentage",
"series"
]
},
{
"name": "data-label-position",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Pass only when the user explicitly requests a position; it only repositions existing data labels and does not enable labels by itself; omit it for chart-type-aware placement",
"enum": [
"auto",
"top",
"bottom",
"left",
"right",
"center",
"inside",
"outside"
]
},
{
"name": "stack",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Stacking mode",
"enum": [
"none",
"normal",
"percent"
]
},
{
"name": "stacked",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Compatibility alias for --stack normal",
"hidden": true
},
{
"name": "smooth",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Use smooth curves; accepts both --smooth=false and --smooth false"
},
{
"name": "color-palette",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Preset chart-level color palette; mutually exclusive with --colors",
"enum": [
"brandColorSeries@v2",
"rainbowColorSeries@v2",
"complementaryColorSeries@v2",
"converseColorSeries@v2",
"primaryColorSeries@v2",
"singleColorSeries-B-@v2",
"singleColorSeries-W-@v2",
"singleColorSeries-G-@v2",
"singleColorSeries-Y-@v2",
"singleColorSeries-O-@v2",
"singleColorSeries-R-@v2",
"singleColorSeries-D-@v2"
]
},
{
"name": "colors",
"kind": "own",
"type": "string_slice",
"required": "optional",
"desc": "Custom chart-level series colors as a comma-separated list of at least two hex colors; mutually exclusive with --color-palette"
},
{
"name": "anchor-cell",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Optional chart anchor cell such as F2; defaults to the right of the data range"
},
{
"name": "width",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Optional chart width; must be paired with --height"
},
{
"name": "height",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Optional chart height; must be paired with --width"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": "Print the request template; no side effects"
}
]
},
"+chart-config-update": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id (XOR with `--sheet-name`)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name (XOR with `--sheet-id`)"
},
{
"name": "chart-id",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Target chart reference_id"
},
{
"name": "title",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Chart title"
},
{
"name": "subtitle",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Chart subtitle"
},
{
"name": "legend-position",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Legend position; hidden removes the legend",
"enum": [
"top",
"bottom",
"left",
"right",
"hidden"
]
},
{
"name": "x-axis-title",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "X-axis title"
},
{
"name": "y-axis-title",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Left Y-axis title"
},
{
"name": "secondary-y-axis-title",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Right Y-axis title"
},
{
"name": "x-axis-label-angle",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "X-axis label angle",
"enum": [
"-90",
"-45",
"0",
"45",
"90"
]
},
{
"name": "y-axis-label-angle",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Left Y-axis label angle",
"enum": [
"-90",
"-45",
"0",
"45",
"90"
]
},
{
"name": "x-axis-min",
"kind": "own",
"type": "float64",
"required": "optional",
"desc": "Lower display bound for a continuous numeric X-axis; must be less than --x-axis-max"
},
{
"name": "x-axis-max",
"kind": "own",
"type": "float64",
"required": "optional",
"desc": "Upper display bound for a continuous numeric X-axis; must be greater than --x-axis-min"
},
{
"name": "y-axis-min",
"kind": "own",
"type": "float64",
"required": "optional",
"desc": "Lower display bound for the left Y-axis; must be less than --y-axis-max"
},
{
"name": "y-axis-max",
"kind": "own",
"type": "float64",
"required": "optional",
"desc": "Upper display bound for the left Y-axis; must be greater than --y-axis-min"
},
{
"name": "data-labels",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Data label content; combine value, category, and percentage in value_category_percentage order for any non-empty combination; series shows series names and none removes labels",
"enum": [
"none",
"value",
"category",
"percentage",
"value_category",
"value_percentage",
"category_percentage",
"value_category_percentage",
"series"
]
},
{
"name": "data-label-position",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Pass only when the user explicitly requests a position; it only repositions existing data labels and does not enable labels by itself; omit it for chart-type-aware placement",
"enum": [
"auto",
"top",
"bottom",
"left",
"right",
"center",
"inside",
"outside"
]
},
{
"name": "last-point-label",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "For line, area, radar, and linear combo series only; true shows a value label on the last data point of every series, while false removes those point labels"
},
{
"name": "stack",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Stacking mode",
"enum": [
"none",
"normal",
"percent"
]
},
{
"name": "stacked",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Compatibility alias for --stack normal",
"hidden": true
},
{
"name": "smooth",
"kind": "own",
"type": "bool",
"required": "optional",
"desc": "Use smooth curves; accepts both --smooth=false and --smooth false"
},
{
"name": "color-palette",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Preset chart-level color palette; mutually exclusive with --colors",
"enum": [
"brandColorSeries@v2",
"rainbowColorSeries@v2",
"complementaryColorSeries@v2",
"converseColorSeries@v2",
"primaryColorSeries@v2",
"singleColorSeries-B-@v2",
"singleColorSeries-W-@v2",
"singleColorSeries-G-@v2",
"singleColorSeries-Y-@v2",
"singleColorSeries-O-@v2",
"singleColorSeries-R-@v2",
"singleColorSeries-D-@v2"
]
},
{
"name": "colors",
"kind": "own",
"type": "string_slice",
"required": "optional",
"desc": "Custom chart-level series colors as a comma-separated list of at least two hex colors; mutually exclusive with --color-palette"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": "Print the request template; no side effects"
}
]
},
"+chart-data-update": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id (XOR with `--sheet-name`)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name (XOR with `--sheet-id`)"
},
{
"name": "chart-id",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Target chart reference_id"
},
{
"name": "data-range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "New data range; include headers unless --header-range is set or the chart already uses detached headers; accepts comma-separated ranges across one or more sheets"
},
{
"name": "header-range",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Optional detached header range; enables detached header mapping, while omission preserves an existing detached mapping"
},
{
"name": "data-direction",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Data series direction; defaults to the existing chart direction when omitted",
"enum": [
"column",
"row"
]
},
{
"name": "dim1-index",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "1-based category/X-axis dimension index within the data range; defaults to the first dimension"
},
{
"name": "dim2-indexes",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Comma-separated 1-based value/Y-axis series indexes within the data range; defaults to all dimensions except dim1"
},
{
"name": "key-index",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Bubble only: 1-based key/name dimension index; mutually exclusive with dim1/dim2 indexes; defaults to 1"
},
{
"name": "x-index",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Bubble only: 1-based X-value dimension index; must be provided with --y-index"
},
{
"name": "y-index",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Bubble only: 1-based Y-value dimension index; must be provided with --x-index"
},
{
"name": "group-index",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Bubble only: optional 1-based group dimension index"
},
{
"name": "size-index",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Bubble only: optional 1-based bubble-size dimension index"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": "Print the request template; no side effects"
}
]
},
"+chart-create": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "properties",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Full chart config JSON. Top-level keys: `position` / `offset` / `size` / `snapshot` (no top-level `data`, no extra nested `properties`); chart data config lives under `snapshot.data` (`refs` / `headerMode` / `dim1` / `dim2`); must include at least one of `snapshot.data.dim1.serie.index` or `dim2.series[].index`, otherwise the server rejects it. Deeply nested — run `--print-schema --flag-name properties` for the full structure.",
"input": [
"file",
"stdin"
]
},
{
"name": "print-example",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Print a minimal ready-to-edit --properties template for a chart type (area|bar|bubble|column|combo|line|pareto|pie|radar|scatter|waterfall) and exit. Purely local: no locator flags, no network; an unknown type lists the available ones"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": "Print the request template; no side effects"
}
]
},
"+chart-update": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "chart-id",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Target chart reference_id"
},
{
"name": "properties",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Chart config patch JSON; send changed fields only by default; omitted fields are preserved, objects merge recursively, and arrays replace as a whole",
"input": [
"file",
"stdin"
]
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+chart-delete": {
"risk": "high-risk-write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "chart-id",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Target chart reference_id"
},
{
"name": "yes",
"kind": "system",
"type": "bool",
"required": "required",
"desc": "Confirm destructive write (exit code 10 without this flag)"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+pivot-list": {
"risk": "read",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "pivot-table-id",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Filter by id"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+pivot-create": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "properties",
"kind": "own",
"type": "string",
"required": "required",
"desc": "JSON: {\"rows\":[...],\"columns\":[...],\"values\":[...],\"filters\":[...],\"show_row_grand_total\":true,\"show_col_grand_total\":true} (data source goes through --source; do not put source here)",
"input": [
"file",
"stdin"
]
},
{
"name": "target-position",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Top-left cell within the target sub-sheet (A1 notation, e.g. `A1`); maps to the top-level `target_position`, default `A1` (not sent when the value is A1). It and `--range` both express placement but map to different wire fields — avoid passing conflicting values for both.",
"default": "A1"
},
{
"name": "target-sheet-id",
"kind": "own",
"type": "string",
"required": "xor",
"desc": "Reference_id of the target sub-sheet where the pivot table will be placed (mutually exclusive with `--target-sheet-name`; takes priority when both given; when both omitted, a new sub-sheet is auto-created to host the pivot — recommended). Distinct from the data-source sheet, which lives inside --source as a 'Sheet'-prefixed A1 reference like 'Sheet1'!A1:D100."
},
{
"name": "target-sheet-name",
"kind": "own",
"type": "string",
"required": "xor",
"desc": "Name of the target sub-sheet where the pivot table will be placed (mutually exclusive with `--target-sheet-id`; when both omitted, a new sub-sheet is auto-created to host the pivot — recommended). Distinct from the data-source sheet, which lives inside --source as a 'Sheet'-prefixed A1 reference like 'Sheet1'!A1:D100."
},
{
"name": "source",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Pivot table source range (A1 notation; format `'SheetName'!StartCell:EndCell`, e.g. `'Sheet1'!A1:D100`)"
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Pivot table top-left placement (single A1 value, e.g. `F1`; create only), maps to `properties.range`; placed at the top-left of the target sub-sheet (a newly created one by default) when omitted. It and `--target-position` both express placement but map to different wire fields — avoid passing conflicting values for both."
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+pivot-update": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "pivot-table-id",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Target pivot table id"
},
{
"name": "properties",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Full or sufficiently complete pivot config (read back with `+pivot-list --pivot-table-id <id>` first, then patch)",
"input": [
"file",
"stdin"
]
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+pivot-delete": {
"risk": "high-risk-write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "pivot-table-id",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Target pivot table id"
},
{
"name": "yes",
"kind": "system",
"type": "bool",
"required": "required",
"desc": "Confirm destructive write (exit code 10 without this flag); delete is irreversible"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+cond-format-list": {
"risk": "read",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "rule-id",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Filter by rule id"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+cond-format-result-get": {
"risk": "read",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id (XOR with `--sheet-name`)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name (XOR with `--sheet-id`)"
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "A1 range, e.g. `A1:F10` (no sheet prefix — use `--sheet-id` / `--sheet-name` to select the sheet)"
},
{
"name": "max-chars",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Max output chars per call; default 500000 (safety cap)",
"default": "500000"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+cond-format-create": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "properties",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Rule config JSON: `style` (required, applied on match), `attrs?` (rule-type-dependent params), `has_ref?`. `rule_type` and `ranges` are separate flags",
"input": [
"file",
"stdin"
]
},
{
"name": "rule-type",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Conditional format rule type; takes precedence over the same-named field inside `--properties`",
"enum": [
"duplicateValues",
"uniqueValues",
"cellIs",
"containsText",
"timePeriod",
"containsBlanks",
"notContainsBlanks",
"dataBar",
"colorScale",
"rank",
"aboveAverage",
"expression",
"iconSet"
]
},
{
"name": "ranges",
"kind": "own",
"type": "string",
"required": "required",
"desc": "A1 ranges where the conditional format applies, as a JSON array (e.g. `[\"A1:A100\",\"C2:C50\"]`); takes precedence over the same-named field inside `--properties`",
"input": [
"file",
"stdin"
]
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+cond-format-update": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "rule-id",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Target rule id"
},
{
"name": "properties",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Rule config JSON, same shape as `+cond-format-create --properties`; update overwrites the entire rule",
"input": [
"file",
"stdin"
]
},
{
"name": "rule-type",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Conditional format rule type; takes precedence over the same-named field inside `--properties`",
"enum": [
"duplicateValues",
"uniqueValues",
"cellIs",
"containsText",
"timePeriod",
"containsBlanks",
"notContainsBlanks",
"dataBar",
"colorScale",
"rank",
"aboveAverage",
"expression",
"iconSet"
]
},
{
"name": "ranges",
"kind": "own",
"type": "string",
"required": "required",
"desc": "A1 ranges where the conditional format applies, as a JSON array (e.g. `[\"A1:A100\",\"C2:C50\"]`); takes precedence over the same-named field inside `--properties`",
"input": [
"file",
"stdin"
]
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+cond-format-delete": {
"risk": "high-risk-write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "rule-id",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Target rule id"
},
{
"name": "yes",
"kind": "system",
"type": "bool",
"required": "required",
"desc": "Confirm destructive write (exit code 10 without this flag); delete is irreversible"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+filter-list": {
"risk": "read",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+filter-create": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Filter range (A1 notation, including header row, e.g. `A1:F1000`); do not duplicate the range field inside `--properties`"
},
{
"name": "properties",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Filter rule JSON: `rules` (per-column rule array), `filtered_columns?` (active column index hint). The flag is optional overall — if provided, `rules` must be non-empty; if omitted, an empty filter is created on `--range` (no column conditions). `range` is a separate flag (do not duplicate inside this JSON)",
"input": [
"file",
"stdin"
]
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+filter-update": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "properties",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Filter rule JSON: `rules` and `filtered_columns?`; update overwrites the entire rule set (pass `rules: []` to clear). `range` is a separate flag",
"input": [
"file",
"stdin"
]
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Range the filter applies to (A1 notation, e.g. `A1:F1000`); takes precedence over the same-named field inside `--properties`"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+filter-delete": {
"risk": "high-risk-write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "yes",
"kind": "system",
"type": "bool",
"required": "required",
"desc": "Confirm destructive write (exit code 10 without this flag); delete is irreversible"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+filter-view-list": {
"risk": "read",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "view-id",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Filter by filter-view reference_id (returns the matching single view)"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+filter-view-create": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "properties",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Filter-view rule JSON: `rules?` (per-column rule array), `filtered_columns?`. `range` and `view_name` are separate flags",
"input": [
"file",
"stdin"
]
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Range the filter view applies to (A1 notation, e.g. `A1:F1000`); takes precedence over the same-named field inside `--properties`; required on create and must cover the header row"
},
{
"name": "view-name",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Filter-view name; auto-assigned by the server when omitted; takes precedence over the same-named field inside `--properties`"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+filter-view-update": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "view-id",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Target filter-view reference_id"
},
{
"name": "properties",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Filter-view rule JSON: `rules?`, `filtered_columns?`; update overwrites the entire rule set (read back with `+filter-view-list` first, then patch; pass `rules: []` to clear). `range` and `view_name` are separate flags",
"input": [
"file",
"stdin"
]
},
{
"name": "range",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Range the filter view applies to (A1 notation, e.g. `A1:F1000`); takes precedence over the same-named field inside `--properties`; omit to keep the current range on update"
},
{
"name": "view-name",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Filter-view name; auto-assigned by the server when omitted on create, kept unchanged when omitted on update; takes precedence over the same-named field inside `--properties`"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+filter-view-delete": {
"risk": "high-risk-write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "view-id",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Target filter-view reference_id"
},
{
"name": "yes",
"kind": "system",
"type": "bool",
"required": "required",
"desc": "Confirm high-risk write (exit code 10 without this flag)"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+sparkline-list": {
"risk": "read",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "group-id",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Filter by group_id"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+sparkline-create": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "properties",
"kind": "own",
"type": "string",
"required": "required",
"desc": "JSON: `{config (shared style), sparklines (array of mini-charts)}`; run `--print-schema` for the full structure",
"input": [
"file",
"stdin"
]
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+sparkline-update": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "group-id",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Target group id"
},
{
"name": "properties",
"kind": "own",
"type": "string",
"required": "required",
"desc": "JSON: `{config, sparklines}`; read back with `+sparkline-list --group-id <id>` first, then patch; run `--print-schema` for the full structure",
"input": [
"file",
"stdin"
]
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+sparkline-delete": {
"risk": "high-risk-write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "group-id",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Target group id"
},
{
"name": "yes",
"kind": "system",
"type": "bool",
"required": "required",
"desc": "Confirm destructive write (exit code 10 without this flag); delete is irreversible"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+float-image-list": {
"risk": "read",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "float-image-id",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Filter by id; lists all float images on the sheet when omitted"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+float-image-create": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "image-name",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Image name, including extension (e.g. `logo.png`)"
},
{
"name": "image-token",
"kind": "own",
"type": "string",
"required": "xor",
"desc": "Image file_token (XOR with `--image-uri`). Common source: `image_token` returned by `+float-image-list`"
},
{
"name": "image-uri",
"kind": "own",
"type": "string",
"required": "xor",
"desc": "Image URI handle returned by the upload flow (not a sheet object reference_id; XOR with `--image-token`); converted to file_token automatically"
},
{
"name": "position-row",
"kind": "own",
"type": "int",
"required": "required",
"desc": "Row anchor of the image's top-left corner (0-based)"
},
{
"name": "position-col",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Column anchor of the image's top-left corner (column letter, e.g. `A` / `B`)"
},
{
"name": "size-width",
"kind": "own",
"type": "int",
"required": "required",
"desc": "Image width in pixels"
},
{
"name": "size-height",
"kind": "own",
"type": "int",
"required": "required",
"desc": "Image height in pixels"
},
{
"name": "offset-row",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Pixel offset within the anchor row, on top of `--position-row`"
},
{
"name": "offset-col",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Pixel offset within the anchor column, on top of `--position-col`"
},
{
"name": "z-index",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Image z-index controlling stacking order"
},
{
"name": "image",
"kind": "own",
"type": "string",
"required": "xor",
"desc": "Local image path; the CLI uploads it as a sheet_image and uses the returned file_token (XOR with --image-token / --image-uri)"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+float-image-update": {
"risk": "write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "float-image-id",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Target float image id"
},
{
"name": "image-name",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Image name, including extension (e.g. `logo.png`)"
},
{
"name": "image-token",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Optional image file_token; mutually exclusive with `--image-uri`; omit both to keep the current image. Common source: `image_token` returned by `+float-image-list`"
},
{
"name": "image-uri",
"kind": "own",
"type": "string",
"required": "optional",
"desc": "Optional image URI handle returned by the upload flow (not a sheet object reference_id); mutually exclusive with `--image-token`; omit both to keep the current image; converted to file_token automatically"
},
{
"name": "position-row",
"kind": "own",
"type": "int",
"required": "required",
"desc": "Row anchor of the image's top-left corner (0-based)"
},
{
"name": "position-col",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Column anchor of the image's top-left corner (column letter, e.g. `A` / `B`)"
},
{
"name": "size-width",
"kind": "own",
"type": "int",
"required": "required",
"desc": "Image width in pixels"
},
{
"name": "size-height",
"kind": "own",
"type": "int",
"required": "required",
"desc": "Image height in pixels"
},
{
"name": "offset-row",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Pixel offset within the anchor row, on top of `--position-row`"
},
{
"name": "offset-col",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Pixel offset within the anchor column, on top of `--position-col`"
},
{
"name": "z-index",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Image z-index controlling stacking order"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+float-image-delete": {
"risk": "high-risk-write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "sheet-id",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet reference_id — required: pass this or `--sheet-name` (exactly one of the two)"
},
{
"name": "sheet-name",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Sheet name — required: pass this or `--sheet-id` (exactly one of the two)"
},
{
"name": "float-image-id",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Target float image id"
},
{
"name": "yes",
"kind": "system",
"type": "bool",
"required": "required",
"desc": "Confirm destructive write (exit code 10 without this flag); delete is irreversible"
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+history-list": {
"risk": "read",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet locator"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet locator"
},
{
"name": "end-version",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "Max version to query (descending pagination). Omit on the first call; pass next_end_version from the previous response."
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+history-revert": {
"risk": "high-risk-write",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet locator"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet locator"
},
{
"name": "history-version-id",
"kind": "own",
"type": "string",
"required": "required",
"desc": "History version to revert to (from +history-list)."
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+history-revert-status": {
"risk": "read",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet locator"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet locator"
},
{
"name": "transaction-id",
"kind": "own",
"type": "string",
"required": "required",
"desc": "Async revert transaction id (from +history-revert)."
},
{
"name": "dry-run",
"kind": "system",
"type": "bool",
"required": "optional",
"desc": ""
}
]
},
"+changeset-get": {
"risk": "read",
"flags": [
{
"name": "url",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
},
{
"name": "spreadsheet-token",
"kind": "public",
"type": "string",
"required": "xor",
"desc": "Spreadsheet token (XOR with `--url`)"
},
{
"name": "start-revision",
"kind": "own",
"type": "int",
"required": "required",
"desc": "Start version (CS revision); the before baseline for review (must be >= 1)"
},
{
"name": "end-revision",
"kind": "own",
"type": "int",
"required": "optional",
"desc": "End version (CS revision); defaults to the latest revision. Gap (end-start+1) must be <= 20",
"default": "-1"
}
]
}
}
Reference in New Issue View Git Blame Copy Permalink