agent-sheet#

agent-sheet is a local spreadsheet CLI for agents. Prefer it when the task needs real workbook structure, formulas, sheet lifecycle, import/export handoff, or a safe shell roundtrip instead of plain CSV cleanup or ad-hoc xlsx library use.

Use it for#

• resolving a workbook and keeping the target explicit with --entry-id
• inspecting workbook structure, sheets, ranges, formulas, and search hits
• writing sparse cells, bounded ranges, anchored review tables, or formula fills
• importing a local workbook, continuing edits, and exporting a final file
• streaming workbook data through shell tools, then writing verified results back
• using bounded script js only when built-in commands do not express the workbook change cleanly

Do not default to#

• reopening the workbook with a local workbook library for reads or writes that agent-sheet already covers
• using shell transforms when a direct write cells, write range, write table, write fill, or sheet ... command is clearer
• trusting metadata-only surfaces such as file info as proof of workbook structure
• finishing after a write without a task-specific verification pass

First path#

1. Run playbooks/00-preflight.md.
2. Resolve the workbook and keep using --entry-id.
3. Choose the smallest matching command via references/command-selection-matrix.md.
4. Verify with playbooks/15-verify.md before finishing.

Hard defaults#

• prefer entryId over unitId for local workbooks and imports
• treat write range as a full bounded rectangle replacement
• treat write table --sheet <name> as an A1-anchored table write with header semantics
• verify shell roundtrips with structure plus sample rows, not row count alone
• use sheet list or inspect workbook for sheet existence and handoff verification

Highest-signal gotchas#

• imported local entries can be healthy even when later file info shows unitId: null; keep operating on entryId
• file info is metadata only; it does not prove sheet count, sheet names, or formula state
• do not run init inside an already initialized workspace tree; nested workspace refusal is expected
• non-English sheet names work, but quote the full A1 range string in the shell
• shell pipelines can preserve the expected row count while still shifting headers or keys; verify the first rows and key columns after writeback

Read references/gotchas.md when the task looks routine but has import/handoff, shell roundtrip, or workspace ambiguity.

Task routing#

TaskRead nextworkspace root, CLI resolution, or workbook target is unclearplaybooks/00-preflight.mdinspect workbook state, extract data, search, or review formulasplaybooks/10-read-analyze.mdplan the smallest safe mutation pathreferences/command-selection-matrix.mdmake data-visible edits or structural workbook changesplaybooks/20-write-safe.mdverify a mutation, shell roundtrip, or handoffplaybooks/15-verify.mdcreate, import, open, or export a local workbookplaybooks/30-file-lifecycle.mdstream workbook data through shell toolsreferences/shell-patterns.mdformatting, layout, or other built-in command gapsplaybooks/40-script-fallback.mdimport/handoff, entryId targeting, file info, or shell verification edge casesreferences/gotchas.md

Output style#

• prefer bounded previews, file paths, or stream output over oversized inline dumps
• use --to-stdout for shell pipelines
• use --to-file --output <path> for large reusable extracts
• when reporting success, include the verification surface you actually used

Ready-made assets#

Use these before improvising shell snippets:

AssetUse whenexamples/roundtrip-awk-write-table.mdbuilding a review sheet through shell roundtripexamples/handoff-verify.mdexporting, importing, and proving handoff structureexamples/template-import-anchor-check.mdimporting a template workbook and checking anchor cellsscripts/verify_csv_preview.pycomparing header, head sample rows, and a key columnscripts/check_csv_cells.pyasserting anchor values or non-empty cells from a CSV snippet

Read next#

Read only the file needed for the task:

FileUse whenplaybooks/00-preflight.mdworkspace or workbook context is not yet resolvedplaybooks/10-read-analyze.mdinspecting workbook state, extracting data, searching, or reviewing formulasreferences/command-selection-matrix.mdpicking the smallest correct command before writingplaybooks/15-verify.mdproving a mutation or handoff actually succeededplaybooks/20-write-safe.mdchoosing the smallest safe mutation pathplaybooks/30-file-lifecycle.mdcreating, importing, opening, or exporting a local workbookplaybooks/40-script-fallback.mdbuilt-in commands cannot express the requested workbook changereferences/shell-patterns.mdthe task is naturally a shell pipelinereferences/gotchas.mdthe task involves common real-world failure modesreferences/js-api-minimal.mdscript js is necessary and must stay tightly boundedexamples/roundtrip-awk-write-table.mdyou need a concrete shell roundtrip exampleexamples/handoff-verify.mdyou need a concrete export/import handoff exampleexamples/template-import-anchor-check.mdyou need a concrete non-English template import example