sheets

CRITICAL, Before starting, you MUST use the Read tool to read ../lark-shared/SKILL.md, which contains information on authentication and permission handling.

Terminology Conventions

The following terms may appear interchangeably in the documentation for this skill, but they refer to the same object. When parsing user input, map them accordingly; do not treat them as distinct concepts:

Each object type is located using its own primary key flag (naming is inconsistent; use this table for reference, do not guess):

Scenario → Command Quick Reference (Check here before guessing command names)

Map high-frequency intents to existing shortcuts / flags. Agents often incorrectly migrate command names or flags from Excel / Google Sheets / Lark OpenAPI. Check this table first to avoid inevitable trial-and-error failures. See individual tool references for complete shortcuts.

⚠️ Positioning flags: +cells-get / +cells-set / +csv-get use --range; +csv-put standardly uses --start-cell (a single top-left anchor cell), but also accepts the --range alias (automatically taking the top-left). Use either one. ⚠️ Reading additional information always goes through +cells-get --include .... There is no --with-styles flag. To view merged cells, use merged_cells in +sheet-info; do not look for a merge flag in +cells-get.

References

References for this skill are divided into two groups: first, read the General Methods and Standards (workflows, ironclad rules, styles, formula rules that cut across all tasks, excluding specific shortcuts) to understand "how to do it right." Then, proceed to Tool References based on the object of operation to check specific shortcuts and call details. For editing tasks, be sure to review the general methods first, as the ironclad rules apply to all tool references.

General Methods and Standards (Read first, applies to all tasks, no specific shortcuts)

Tool References by Object (includes shortcuts)

Common Flag Quick Reference

Each shortcut in the references is marked with a line of badges indicating the common/system flags it supports, for example:

• _Common Four-Piece Set · System: --dry-run_, URL/token + sheet positioning (one of each group must be provided, see "Common Flags" below), plus --dry-run
• _Common: URL/token (no sheet positioning) · System: --yes, --dry-run_, Accepts only URL/token, common for shortcuts like +batch-update that do not require sheet positioning.

Only names are listed in the badges. Types / requirements / descriptions are declared uniformly in this section:

Common Flags (Resource Positioning)

Common Four-Piece Set = --url / --spreadsheet-token / --sheet-id / --sheet-name, divided into two XOR groups. One of each group must be provided (XOR = one of two is mandatory, not "optional"):

1. Spreadsheet positioning (mandatory): Choose one of --url or --spreadsheet-token. One must be provided. If neither is provided → validation error specify at least one of --url or --spreadsheet-token; if both are provided → mutual conflict.
   • --url only parses links containing /sheets/ and /spreadsheets/ (extracts the token from the path; you can also pass the raw token directly to --spreadsheet-token). Other link formats will not be parsed as spreadsheet tokens.
   • ⚠️ /wiki/ knowledge base links cannot be used directly as spreadsheet positioning: A wiki link might point to a spreadsheet, a document, or a base. --url will not automatically parse a wiki token into a spreadsheet token; passing it directly will fail. You must first resolve it into a real document token, lark-cli wiki +node-get --node-token "<wiki link or token>" and, after confirming the returned obj_type is sheet, use its obj_token as the --spreadsheet-token (see ../lark-wiki/SKILL.md for parsing details).
   • Exception: +workbook-create creates a new table that does not yet exist and does not accept any spreadsheet / sheet positioning flags (only --title / --folder-token / --headers / --values).
2. Sheet positioning (mandatory for Common Four-Piece Set shortcuts): Choose one of --sheet-id or --sheet-name. One must be provided. If neither is provided → validation error specify at least one of --sheet-id or --sheet-name.
   • ⚠️ Do not guess Sheet1 if the sheet name is uncertain: Unless the user explicitly states the sheet name/id, or the context (previous tool calls / URL anchor ?sheet=xxx) has already provided a specific value, the first step is to call +workbook-info --url "..." (or --spreadsheet-token) to get the sheets[].sheet_id / sheets[].title list and then select. In Chinese environments, sub-sheets are often named "Data" / "Sheet" (no number) / "Worksheet 1" / business names. Guessing Sheet1 will likely hit sheet not found, costing an extra failed call + retry.
   • ⚠️ The Sheet1! prefix in --range cannot replace sheet positioning: Even if you write --range 'Sheet1!A1:B2', you must still pass --sheet-id or --sheet-name, otherwise the same error will occur.
   • ⚠️ A1 references containing ! (--source / --range / --ranges): Start the shell session with set +H to disable bash history expansion, otherwise "Sheet1!A1" will be blocked as event not found. Sheet names containing special characters (- / spaces / non-ASCII) must be wrapped in single quotes internally, e.g., --source "'Sales-2025'!A1:D100".
   • Exception: Shortcuts marked _Common: URL/token (no sheet positioning) ..._ (e.g., +workbook-info / +workbook-export / +batch-update / +dropdown-update|delete / +cells-batch-set-style / +cells-batch-clear / +sheet-create) do not accept or require sheet positioning; just provide one set of spreadsheet positioning. +pivot-create uses --target-sheet-id / --target-sheet-name (XOR, both can be omitted; see lark-sheets-pivot-table for landing details).

Unified Calling Paradigm (all examples for Common Four-Piece Set shortcuts follow this shape, both positioning groups are indispensable):

lark-cli sheets <shortcut> <workbook positioning> <sheet positioning> <other flags>
#   workbook positioning: --url "..."        or --spreadsheet-token "..."           (choose one, mandatory)
#   sheet positioning:    --sheet-id "$SID"  or --sheet-name "<real sheet name>"    (choose one, mandatory; do not use placeholders)
# Example: lark-cli sheets +csv-get --url "https://.../sheets/shtXXX" --sheet-name "<real sheet name>" --range "A1:F30"
# Note: Do not guess "Sheet1" as the real sheet name, most tables do not use this; first use +workbook-info to get sheets[].title then substitute.

System Flags

Agent Usage Tip: When writing composite JSON flags (--cells / --properties / --operations / --border-styles / --sort-keys / --options, etc.), if you are unsure of the structure, first run lark-cli sheets <shortcut> --print-schema --flag-name <name> to read the complete JSON Schema before constructing the payload. This is more accurate than relying on reference quick-reference tables and avoids rejection by the server due to spelling errors or missing fields. The ## Schemas section of the reference only provides a single-layer structure; for deep structures, rely on --print-schema or real examples in ## Examples.

Flag Content Types and Output Conventions (Terminology)

• JSON-class inputs in the flag table are marked in three categories: Composite JSON = deeply nested objects (use --print-schema to get the full structure); Simple JSON = 1D/2D scalar arrays (e.g., ["sheet1!A1:B2",...] / [["alice",95]], simple structure, no print-schema needed); Non-JSON Text = raw text (e.g., CSV). --print-schema is only valid for Composite JSON flags (simple JSON flags of the same shortcut, like --colors, are not included).
• envelope: All shortcuts return a unified outer structure {ok, identity, data, ...}. In the body, envelope.data refers to the business data layer (e.g., annotated_csv for +csv-get); write operations do not automatically read back. If verification is needed, call the corresponding +*-list / +*-get / +cells-get yourself.

Composite JSON / Large Inputs: Prefer Stdin

For inputs marked as supporting Stdin in the flag help, if the payload is large, contains special characters like newlines/quotes, or is already in a file, prefer using stdin (-) to avoid command line length limits and shell escaping issues.

Recommended approach: Write the payload to a temporary file outside the user's project directory (use the system temporary directory to avoid polluting the project), then feed it in via stdin:

# TMPFILE points to a payload file in the system temporary directory (use tempfile.gettempdir() / os.tmpdir() in scripts to get the temp directory)
lark-cli sheets +cells-set --url "..." --sheet-name "Sheet1" --range "A1:B2" --cells - < "$TMPFILE"

@file with an absolute path will be rejected, and do not follow the error prompt after rejection. For security reasons, @file only accepts relative paths under the cwd; passing an absolute path outside the cwd will be rejected. The error message will suggest "cd to the target directory or use a relative path", do not follow either: cd-ing or writing temporary files into the user's project directory will pollute the working directory. The correct solution is to use stdin (--<flag> - < file).