maybeai-sheet-cli 0.4.1

CLI for common MaybeAI spreadsheet operations

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):

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:

pip install maybeai-sheet-cli

Upgrade to the latest release:

mbs update          # when installed via pip or pipx
pipx upgrade maybeai-sheet-cli   # alternative on pipx installs

Install a specific version:

mbs update --version 0.3.2
pipx install maybeai-sheet-cli==0.3.2 --force   # pipx reinstall pin

Uninstall:

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:

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:

mbs workbook list-user-workbooks --limit 20

Read a bounded range:

mbs excel-worksheet range read --doc-id abc123 --worksheet-name Sheet1 --range A1:D20

List worksheets:

mbs workbook list-worksheets --doc-id abc123

Inspect the first worksheet-backed table:

mbs excel-table metadata --doc-id abc123 --worksheet-name Sheet1 --table-id 1

Create a workbook:

mbs workbook create --title "Board Pack"

Import a workbook-style .xlsx through the default Excelize path:

mbs workbook import ./report.xlsx

Import a large table-like .xlsx into SheetTable/PG:

mbs workbook import ./large-table.xlsx --engine postgres

Append rows and verify:

mbs excel-table insert --doc-id abc123 --worksheet-name Sheet1 --table-id 1 --rows rows.json --verify

Grant workbook access:

mbs share create --doc-id abc123 --email [e-mail] --role viewer

Rename a worksheet and inspect a destructive row delete before sending it:

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:

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.

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.

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.

# 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 [e-mail] --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:

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

python3 -m venv .venv
. .venv/bin/activate
pip install -U pip
pip install -e .

Run tests:

python -m unittest discover -s tests -v