maybeai-sheet-cli 0.3.2__tar.gz → 0.4.1__tar.gz

maybeai_sheet_cli-0.4.1/PKG-INFO

@@ -0,0 +1,629 @@
+Metadata-Version: 2.4
+Name: maybeai-sheet-cli
+Version: 0.4.1
+Summary: CLI for common MaybeAI spreadsheet operations
+Project-URL: Homepage, https://github.com/OmniMCP-AI/maybeai-sheet-cli
+Project-URL: Repository, https://github.com/OmniMCP-AI/maybeai-sheet-cli
+Project-URL: Issues, https://github.com/OmniMCP-AI/maybeai-sheet-cli/issues
+Author: OmniMCP-AI
+License: Proprietary
+Keywords: cli,excel,maybeai,spreadsheet
+Classifier: Environment :: Console
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: rich<14,>=13.7
+Requires-Dist: typer<1,>=0.12
+Description-Content-Type: text/markdown
+
+# maybeai-sheet-cli
+
+CLI for MaybeAI spreadsheet operations.
+
+`mbs` wraps the MaybeAI spreadsheet HTTP APIs behind a stable command-line interface for humans, CI jobs, and agents.
+
+## Install
+
+On Debian/Ubuntu and other **PEP 668** systems, do **not** use bare `pip install` on system Python. Use **pipx** (recommended for CLIs):
+
+```bash
+sudo apt install -y pipx python3-venv
+pipx ensurepath
+# re-login or: source ~/.bashrc
+
+pipx install maybeai-sheet-cli
+mbs --version
+```
+
+For local venvs or macOS/dev machines, plain pip is fine:
+
+```bash
+pip install maybeai-sheet-cli
+```
+
+Upgrade to the latest release:
+
+```bash
+mbs update          # when installed via pip or pipx
+pipx upgrade maybeai-sheet-cli   # alternative on pipx installs
+```
+
+Install a specific version:
+
+```bash
+mbs update --version 0.3.2
+pipx install maybeai-sheet-cli==0.3.2 --force   # pipx reinstall pin
+```
+
+Uninstall:
+
+```bash
+pipx uninstall maybeai-sheet-cli
+# not: pip uninstall -U  (-U is invalid for uninstall)
+```
+
+## Requirements
+
+- Python 3.10+
+- `MAYBEAI_API_TOKEN`
+
+## Configure
+
+Set your API token:
+
+```bash
+export MAYBEAI_API_TOKEN="YOUR_TOKEN"
+```
+
+Optional global flags:
+
+- `--base-url` to point at a different MaybeAI API host
+- `--output json|table|yaml`
+- `--timeout <seconds>`
+- `--verbose`
+
+## Quick Start
+
+The examples below follow the target protocol names. The currently shipped
+compatibility aliases are listed in the Implemented Command Tree.
+
+List user-visible workbooks:
+
+```bash
+mbs workbook list-user-workbooks --limit 20
+```
+
+Read a bounded range:
+
+```bash
+mbs excel-worksheet range read --doc-id abc123 --worksheet-name Sheet1 --range A1:D20
+```
+
+List worksheets:
+
+```bash
+mbs workbook list-worksheets --doc-id abc123
+```
+
+Inspect the first worksheet-backed table:
+
+```bash
+mbs excel-table metadata --doc-id abc123 --worksheet-name Sheet1 --table-id 1
+```
+
+Create a workbook:
+
+```bash
+mbs workbook create --title "Board Pack"
+```
+
+Import a workbook-style `.xlsx` through the default Excelize path:
+
+```bash
+mbs workbook import ./report.xlsx
+```
+
+Import a large table-like `.xlsx` into SheetTable/PG:
+
+```bash
+mbs workbook import ./large-table.xlsx --engine postgres
+```
+
+Append rows and verify:
+
+```bash
+mbs excel-table insert --doc-id abc123 --worksheet-name Sheet1 --table-id 1 --rows rows.json --verify
+```
+
+Grant workbook access:
+
+```bash
+mbs share create --doc-id abc123 --email teammate@example.com --role viewer
+```
+
+Rename a worksheet and inspect a destructive row delete before sending it:
+
+```bash
+mbs excel-worksheet rename --doc-id abc123 --worksheet-name Old --new-name New
+mbs excel-worksheet row delete --doc-id abc123 --worksheet-name Sheet1 --row 10 --dry-run
+mbs excel-worksheet row delete --doc-id abc123 --worksheet-name Sheet1 --row 10 --yes
+```
+
+Search, style, inspect history, and export:
+
+```bash
+mbs excel-worksheet range search --doc-id abc123 --worksheet-name Sheet1 --query revenue --max-results 20
+mbs excel-worksheet style freeze-panes --doc-id abc123 --worksheet-name Sheet1 --cell B2
+mbs excel-worksheet range calculate --doc-id abc123 --worksheet-name Sheet1 --cell E2 --formula "=SUM(B2:D2)"
+mbs version list --doc-id abc123 --limit 10
+mbs workbook export --doc-id abc123 --out workbook.xlsx
+```
+
+## Relationship
+1 workbok
+ |                         \
+N db_worksheet(PG)   N excel_worksheets
+                            |                        \
+                      M(N>1) db_worksheet(db_table)   J(<N) excel_table
+
+CLI command names normalize these relationship labels to hyphenated groups:
+`excel_worksheet` becomes `excel-worksheet`, `excel_table` becomes
+`excel-table`, and `db_worksheet(db_table)` becomes `db-table`.
+
+## Implemented Command Tree
+
+This is the current shipped command surface. The full roadmap tree below is
+separate and includes planned or deferred commands.
+
+```text
+mbs
+├── update
+│   └── Update maybeai-sheet-cli from PyPI.
+│
+├── workbook
+│   ├── create             Create a new workbook.
+│   ├── create-from-file   Import an .xlsx file.
+│   ├── import             Preferred alias for create-from-file.
+│   ├── metadata           Inspect workbook profile and routing metadata.
+│   ├── list-user-workbooks
+│   │                      Preferred alias for bounded user workbook listing.
+│   ├── list-worksheets    List worksheets in a workbook.
+│   ├── list               List user workbooks with bounded output.
+│   ├── search             Search user workbooks with bounded output.
+│   ├── manifest           Compatibility alias for metadata.
+│   └── capabilities       Inspect workbook capability/profile metadata.
+│
+├── excel-worksheet
+│   ├── metadata           Inspect worksheet metadata through workbook profile.
+│   └── list-table         List worksheet/table metadata for a workbook.
+│
+├── excel-table
+│   ├── metadata           Resolve a worksheet-backed table from workbook metadata.
+│   ├── schema             Infer schema from a resolved worksheet-backed table range.
+│   ├── sample             Return bounded table sample rows.
+│   ├── read               Read a resolved worksheet-backed table range.
+│   └── insert             Insert row objects into a worksheet-backed table.
+│
+├── db-table
+│   ├── metadata           Resolve PG/SheetTable-backed worksheet metadata.
+│   ├── schema             Infer schema from a bounded PG read.
+│   ├── sample             Return bounded PG table sample rows.
+│   ├── read               Read PG-backed table rows through routed APIs.
+│   └── insert             Insert rows into a PG-backed table.
+│
+├── worksheet
+│   ├── list               List worksheets in a workbook.
+│   ├── create             Create a worksheet, optionally with starter values.
+│   ├── rename             Rename a worksheet.
+│   ├── delete             Delete a worksheet; requires --yes unless --dry-run.
+│   ├── copy               Copy a worksheet.
+│   └── move               Move a worksheet to a zero-based index.
+│
+├── range
+│   ├── read               Read a bounded A1 range.
+│   ├── write              Write a JSON matrix into an A1 range.
+│   ├── clear              Clear an A1 range.
+│   └── search             Search a worksheet with bounded results.
+│
+├── row
+│   ├── insert             Insert rows.
+│   ├── delete             Delete rows; requires --yes unless --dry-run.
+│   └── move               Move rows.
+│
+├── column
+│   ├── insert             Insert columns.
+│   ├── delete             Delete columns; requires --yes unless --dry-run.
+│   ├── move               Move columns.
+│   └── width              Set column width.
+│
+├── formula
+│   ├── read               Read formulas with FORMULA render mode.
+│   ├── set                Set one formula cell.
+│   ├── batch-set          Set formula ranges from a JSON operations file.
+│   ├── recalculate        Recalculate formulas for a worksheet/workbook.
+│   ├── calculate          Calculate one formula cell.
+│   └── lineage            Trace formula lineage for one cell.
+│
+├── style
+│   ├── freeze-panes       Freeze rows/columns using an A1 cell boundary.
+│   ├── auto-filter set    Set worksheet auto-filter range.
+│   ├── auto-filter remove Remove worksheet auto-filter.
+│   ├── columns-width      Set column widths.
+│   └── rows-height        Set row heights.
+│
+├── history
+│   ├── list               List workbook versions with bounded output.
+│   └── read               Read a workbook version.
+│
+├── file
+│   ├── export             Export workbook bytes to --out.
+│   ├── list               List files with bounded output.
+│   └── search             Search files with bounded output.
+│
+├── share
+│   ├── visibility         Set workbook visibility.
+│   ├── grant              Grant a user permission.
+│   ├── permission         Read current permission.
+│   ├── remove             Remove a user's access.
+│   └── list               List sharing entries.
+│
+├── raw
+│   └── post               Low-level POST escape hatch for routed API paths.
+│
+└── sheet                  Legacy compatibility aliases.
+    ├── read
+    ├── read-range
+    ├── read-many
+    ├── named-range
+    ├── headers
+    ├── worksheets
+    ├── formulas
+    ├── write-range
+    ├── clear-range
+    ├── append
+    ├── upsert
+    ├── formula-set
+    ├── formula-batch-set
+    ├── recalculate
+    └── create-worksheet
+```
+
+## Full Command Tree
+
+The reviewed tree below is the source of truth for the protocol shape. Product
+model labels in this block use underscores; CLI names in examples and future
+router code should normalize them to hyphenated command groups such as
+`excel-worksheet`, `excel-table`, and `db-table`. The older `sheet ...`
+commands remain available as compatibility aliases. This tree includes
+implemented, planned, deferred, and not-recommended command surfaces.
+
+Status legend for the full tree:
+
+- `NOW`: released in the current CLI under this command shape.
+- `API`: route exists or is expected, but the target command wrapper/refactor is
+  not released under this shape yet.
+- `PG`: SheetTable/PG-specific; defer until exposed through the public API.
+- `PLAN`: needs a backend/product contract before implementation.
+- `DEFER`: intentionally not part of the clean agent-first surface yet.
+- `SKIP`: not recommended for this CLI.
+
+```text
+mbs
+├── update
+│   └── Update maybeai-sheet-cli from PyPI.
+│
+├── workbook
+│   ├── metadata                 API   Inspect workbook profile and routing metadata.(workshets)
+|   |- source                   PLAN  Similar to NotebookLM source (menu on the left).
+│   ├── create                   NOW   Create a new workbook.
+│   ├── create-from-file         NOW   Import an .xlsx file.
+│   ├── import                   NOW   Preferred alias for create-from-file.
+│   ├── list-user-workbooks       API   List user workbooks with bounded output.
+|       list-worksheets           API   List worksheets, including engine.
+│   ├── search                   NOW   Search user workbooks with bounded output.
+│   ├── export                   API   Export workbook bytes.
+│   └── copy                     API   Copy a workbook.
+│   ├── upload                   API   Upload a file through workbook import flow.
+│   ├── update                   API   Update a stored workbook file not change doc_id
+│   ├── export                   API   Export workbook bytes to --out.
+│   ├── delete                   API   Delete a stored file.
+│   └── rename                   API   Rename a stored file.
+│
+├── excel_worksheet
+│   ├── list-table               API   List worksheets in a workbook.
+│   ├── create                   API   Create a worksheet, optionally with starter values.
+│   ├── update                   API   Update worksheet metadata.
+│   ├── sample                   PLAN  Return bounded worksheet/range sample rows.
+│   ├── delete                   API   Delete a worksheet; requires --yes unless --dry-run.
+│   ├── rename                   API   Rename a worksheet.
+│   ├── move                     API   Move a worksheet to a zero-based index.
+│   └── copy                     API   Copy a worksheet.
+|   └── metadata                 API   Include table meta: range, header, table id, data summary.
+│
+├── excel_table
+│   ├── create                   PLAN   Create a table view from a worksheet range.
+│   ├── update                   PLAN   Update table view metadata or range.
+│   ├── delete                   PLAN   Delete a table view; requires --yes unless --dry-run.
+│   ├── schema                   API   Infer table schema from a resolved table range.
+│   ├── sample                   API   Return bounded table sample rows.
+│   ├── read                     API   Read header-aware table rows.
+│   ├── insert                   API   Insert table rows.
+|   └── metadata                 API   Include table meta: range, header, table id, data summary.
+|
+├── excel_worksheet range
+│   ├── read                     API   Read a bounded A1 range.
+│   ├── write                    API   Write a JSON matrix into an A1 range.
+│   ├── clear                    API   Clear an A1 range.
+│   ├── read-many                DEFER Legacy alias only until a real batch API exists.
+│   ├── copy                     API   Copy a range.
+│   ├── search                   API   Search a worksheet with bounded results.
+│   └── used-range               PLAN  Return worksheet used range after a routed contract exists.
+│   ├── set-formula              API   Set one formula cell.
+│   ├── calculate                API   Calculate one formula cell.
+|   |- lineage                   API   Trace cell/range lineage.
+│
+├── db_worksheet(AKA db_table)
+│   ├── create                   PG    Create a PG-backed table.
+│   ├── update                   PG    Update PG-backed table metadata.
+│   ├── delete                   PG    Delete a PG-backed table; requires --yes unless --dry-run.
+│   ├── schema                   API   Infer table schema from a bounded PG read.
+│   ├── sample                   API   Return bounded table sample rows.
+│   ├── read                     API   Read PG-backed table rows.
+│   ├── insert                   API   Insert PG-backed table rows.
+|   └── metadata                 API   Include table meta, backend id, schema, and data summary.
+│
+├── excel_worksheet row
+│   ├── insert                   API   Insert rows.
+│   ├── delete                   API   Delete rows; requires --yes unless --dry-run.
+│   └── move                     API   Move rows.
+│
+├── excel_worksheet column
+│   ├── insert                   API   Insert columns.
+│   ├── delete                   API   Delete columns; requires --yes unless --dry-run.
+│   ├── move                     API   Move columns.
+│   ├── width                    API   Set column width.
+│   └── append                   API   Append columns.
+│
+├── excel_worksheet chart
+│   ├── list                     API   List charts in a workbook or dashboard.
+│   ├── get                      API   Read one chart spec and source binding.
+│   ├── preview                  PLAN  Preview one chart from its spec/source binding.
+│   ├── create-config                     API   Create one chart from a chart spec.
+│   ├── update                   API   Update one chart from a chart spec.
+│   ├── refresh                  PLAN  Refresh one chart from its current source binding.
+│   └── delete                   API   Delete one chart.
+│
+├── excel_worksheet dashboard
+│   ├── manifest                 PLAN  Read dashboard, chart, metric, layout, and lineage metadata.
+│   ├── create-config            PLAN  Compose chart ids/specs into a dashboard config.
+│   ├── validate                 PLAN  Validate dashboard layout, permissions, filters, and metrics.
+│   └── refresh                  PLAN  Refresh dashboard charts from their current source bindings.
+│   └── delete  
+│
+│
+├── excel_worksheet style
+│   ├── cell batch-set           API   Apply cell style batches from JSON.
+│   ├── columns-width            API   Set column widths.
+│   ├── rows-height              API   Set row heights.
+│   ├── freeze-panes             API   Freeze rows/columns using an A1 boundary.
+│   ├── gridlines toggle         API   Toggle worksheet gridlines.
+│   ├── auto-filter set          API   Set worksheet auto-filter range.
+│   ├── auto-filter remove       API   Remove worksheet auto-filter.
+│   ├── filter-values            API   Apply filter values.
+│   ├── conditional-formats set  API   Set conditional formatting rules.
+│   ├── worksheet plan           API   Generate a worksheet styling plan.
+│   └── worksheet apply          API   Apply a worksheet styling plan.
+│
+├── excel_worksheet  image
+│   ├── read                     API   Read worksheet images.
+│   ├── insert                      API   Add an image file.
+│   └── delete                   API   Delete an image.
+│
+├── version
+│   ├── list                     API   List workbook history with bounded output.
+│   └── restore                  PLAN  Restore a workbook history version after a routed contract exists.
+│
+│
+├── share
+│   ├── create                   API   Create or grant sharing access.
+│   ├── remove                   API   Remove a user's access.
+│   ├── modify                   API   Modify sharing access.
+│
+│
+└── sheet                  Legacy compatibility aliases.
+    ├── read
+    ├── read-range
+    ├── read-many
+    ├── named-range
+    ├── headers
+    ├── worksheets
+    ├── formulas
+    ├── write-range
+    ├── clear-range
+    ├── append
+    ├── upsert
+    ├── formula-set
+    ├── formula-batch-set
+    ├── recalculate
+    └── create-worksheet
+```
+
+Full tree examples:
+
+These examples cover every top-level category. Commands marked `API`, `PLAN`,
+`PG`, or `DEFER` show the intended CLI shape, but are not guaranteed to be
+available until their status moves to `NOW`. They use hyphenated CLI command
+names even when the reviewed protocol tree uses underscore model labels.
+
+```bash
+# update
+mbs update --check
+
+# workbook
+mbs workbook metadata --doc-id abc123  # API
+mbs workbook list-user-workbooks --limit 20  # API
+mbs workbook list-worksheets --doc-id abc123  # API
+mbs workbook export --doc-id abc123 --out workbook.xlsx  # API
+mbs workbook copy --doc-id abc123 --name "Budget Copy"  # API
+mbs workbook delete --doc-id abc123 --dry-run  # API
+
+# excel-worksheet
+mbs excel-worksheet create --doc-id abc123 --name Actuals  # API
+mbs excel-worksheet update --doc-id abc123 --worksheet-name Actuals --title "Actuals FY26"  # API
+mbs excel-worksheet metadata --doc-id abc123 --worksheet-name Actuals  # API
+mbs excel-worksheet sample --doc-id abc123 --worksheet-name Actuals --range A1:Z5000 --limit 50  # PLAN
+
+# excel-worksheet range
+mbs excel-worksheet range read --doc-id abc123 --worksheet-name Actuals --range A1:D20  # API
+mbs excel-worksheet range used-range --doc-id abc123 --worksheet-name Actuals  # PLAN
+mbs excel-worksheet range lineage --doc-id abc123 --worksheet-name Model --cell E2 --format tree  # API
+
+# excel-table
+mbs excel-table metadata --doc-id abc123 --worksheet-name Orders --table-id 1  # API
+mbs excel-table schema --doc-id abc123 --worksheet-name Orders --table-id 1  # API
+mbs excel-table sample --doc-id abc123 --worksheet-name Orders --table-id 1 --limit 50  # API
+mbs excel-table read --doc-id abc123 --worksheet-name Orders --table-id 1 --limit 50  # API
+mbs excel-table insert --doc-id abc123 --worksheet-name Orders --table-id 1 --rows rows.json  # API
+mbs excel-table style columns-width --doc-id abc123 --worksheet-name Orders --table-id 1 --column B --width 120  # API
+
+# db-table
+mbs db-table metadata --doc-id abc123 --name orders-large  # API
+mbs db-table schema --doc-id abc123 --name orders-large  # API
+mbs db-table sample --doc-id abc123 --name orders-large --limit 50  # API
+mbs db-table read --doc-id abc123 --name orders-large --limit 50  # API
+mbs db-table insert --doc-id abc123 --name orders-large --rows rows.json  # API
+
+# row
+mbs excel-worksheet row insert --doc-id abc123 --worksheet-name Actuals --row 10 --count 2  # API
+
+# column
+mbs excel-worksheet column width --doc-id abc123 --worksheet-name Actuals --column B --width 120  # API
+mbs excel-worksheet column append --doc-id abc123 --worksheet-name Actuals --values columns.json  # API
+
+# cell
+mbs excel-worksheet range lineage --doc-id abc123 --worksheet-name Model --cell E2 --format tree  # API
+
+# formula
+mbs excel-worksheet range calculate --doc-id abc123 --worksheet-name Model --cell E2 --formula "=SUM(B2:D2)"  # API
+mbs excel-worksheet range set-formula --doc-id abc123 --worksheet-name Model --cell E2 --formula "=SUM(B2:D2)"  # API
+
+# chart
+mbs excel-worksheet chart create-config --doc-id abc123 --worksheet-name Dashboard --cell J2 --spec chart.json  # API
+mbs excel-worksheet chart refresh --doc-id abc123 --worksheet-name Dashboard --chart-id chart_monthly_revenue  # PLAN
+
+# dashboard
+mbs excel-worksheet dashboard manifest --doc-id abc123 --worksheet-name Dashboard --dashboard-id dash_revenue  # PLAN
+mbs excel-worksheet dashboard create-config --doc-id abc123 --worksheet-name Dashboard --name "Revenue Dashboard" --spec dashboard.json  # PLAN
+mbs excel-worksheet dashboard refresh --doc-id abc123 --worksheet-name Dashboard --dashboard-id dash_revenue  # PLAN
+
+# style
+mbs excel-worksheet style freeze-panes --doc-id abc123 --worksheet-name Actuals --cell B2  # API
+mbs excel-worksheet style conditional-formats set --doc-id abc123 --worksheet-name Actuals --spec conditional_formats.json  # API
+
+# image
+mbs excel-worksheet image insert --doc-id abc123 --worksheet-name Dashboard --cell A1 --file logo.png  # API
+
+# version
+mbs version list --doc-id abc123 --limit 10  # API
+mbs version restore --doc-id abc123 --version-id v42 --dry-run  # PLAN
+
+# share
+mbs share create --doc-id abc123 --email teammate@example.com --role viewer  # API
+
+# sheet
+mbs sheet read --doc-id abc123 --worksheet-name Sheet1 --range A1:D20
+```
+
+Refactor planning is tracked separately from this README:
+`docs/superpowers/plans/2026-07-01-mbs-two-engine-command-refactor.md`.
+
+Not recommended as first-class CLI commands:
+
+```text
+validation create/update/delete                  PLAN
+protection protect/unprotect                     PLAN
+sort range/table                                 PLAN
+comment create/update/delete                     PLAN
+named-range create/update/delete                 PLAN
+macro/vba                                        SKIP
+power-query                                      SKIP
+power-pivot                                      SKIP
+workbook diff                                    PLAN
+dependency graph beyond cell lineage             PLAN
+```
+
+Relationship guide:
+
+- Use `workbook` for file-level creation, upload/import, and manifest checks.
+- Use `excel-worksheet` for Excel tab lifecycle operations and worksheet/range
+  inspection.
+- Use `excel-worksheet range` for coordinate-based reads, writes, formulas, and
+  cell lineage.
+- Use `excel-table` for worksheet-backed table views. One Excel worksheet can
+  contain multiple tables, so workbook metadata should expose simple ordinal
+  table ids such as `1`, `2`, `3`, and `4`, each mapped to the real worksheet
+  range behind the scenes. `excel-table` commands should accept optional
+  `--table-id`; when omitted, the CLI should default to `--table-id 1` only
+  inside an unambiguous worksheet target.
+- Use `db-table` for PG/SheetTable-backed tables. These are not worksheet
+  ranges, so prefer human-readable `--name` or backend ids instead of worksheet
+  `--table-id`.
+- Use `excel-worksheet row` and `excel-worksheet column` for structural
+  row/column changes.
+- Use `excel-worksheet style` for worksheet layout operations like freeze
+  panes, filter ranges, widths, and heights.
+- Use `excel-table style` when the same styling operation should be scoped to a
+  table's resolved worksheet range.
+- Use `excel-worksheet chart` for CRUD, preview, and refresh of individual
+  source-backed visualizations before composing dashboards.
+- Use `excel-worksheet dashboard` to compose chart ids/specs into BI asset or
+  dashboard worksheet lifecycles.
+- Use `excel-worksheet image` for lower-level report workflows after routed
+  public API verification.
+- Use `version` for workbook history inspection and restore.
+- Use `share` for visibility and collaborator access.
+
+Targeting notes:
+
+- Most commands accept `--doc-id`, `--url`, or `--uri`.
+- Prefer `--worksheet-name` when the backend route supports names.
+- Use `--table-id` when operating on an `excel-table`. It is a simple ordinal
+  from workbook metadata, for example `--table-id 1`, and maps internally to
+  table metadata such as `worksheet_name` and `range`.
+- Use `--name` or backend ids when operating on a `db-table`.
+- Use `--gid` only for legacy gid-specific compatibility aliases.
+
+## Input Rules
+
+- Use `--doc-id`, `--url`, or `--uri` to identify a workbook.
+- Use `--worksheet-name` when the endpoint supports it.
+- Use `--table-id` when operating on an `excel-table`; default to `1` only when
+  the target worksheet is unambiguous.
+- Use `--name` or backend ids when operating on a `db-table`.
+- Use `--gid` for gid-specific sheet targeting.
+- File inputs like `--rows`, `--values`, `--targets`, and `--operations` must be JSON.
+
+## Output
+
+Default output is JSON. `table` is optimized for sheet-like payloads; `yaml` is also supported.
+
+## Development
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -U pip
+pip install -e .
+```
+
+Run tests:
+
+```bash
+python -m unittest discover -s tests -v
+```