maybeai-sheet-cli 0.4.0

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

Read a bounded range:

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

List worksheets:

mbs worksheet list --doc-id abc123

Read headers from a worksheet:

mbs table headers --doc-id abc123 --gid 3

Create a workbook:

mbs workbook create --title "Board Pack"

Upload 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 table append-rows --doc-id abc123 --gid 3 --rows rows.json --verify

Make a workbook public for viewers:

mbs share visibility --doc-id abc123 --visibility public --public-permission viewer

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

mbs worksheet rename --doc-id abc123 --worksheet-name Old --new-name New
mbs row delete --doc-id abc123 --worksheet-name Sheet1 --row 10 --dry-run
mbs row delete --doc-id abc123 --worksheet-name Sheet1 --row 10 --yes

Search, style, inspect history, and export:

mbs range search --doc-id abc123 --worksheet-name Sheet1 --query revenue --max-results 20
mbs style freeze-panes --doc-id abc123 --worksheet-name Sheet1 --cell B2
mbs formula calculate --doc-id abc123 --worksheet-name Sheet1 --cell E2 --formula "=SUM(B2:D2)"
mbs history list --doc-id abc123 --limit 10
mbs file export --doc-id abc123 --out workbook.xlsx

Commands

The preferred command groups are workbook, worksheet, range, table, row, column, formula, style, history, file, share, and raw. The older sheet ... commands remain available as compatibility aliases.

mbs
├── update
│   └── Update maybeai-sheet-cli from PyPI.
│
├── workbook
│   ├── create             Create a new workbook.
│   ├── create-from-file   Upload/import an .xlsx file.
│   ├── import             Preferred alias for create-from-file.
│   ├── manifest           Inspect workbook profile and routing metadata.
│   └── capabilities       Inspect workbook capability/profile metadata.
│
├── 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.
│
├── table
│   ├── headers            Read header row metadata.
│   ├── append-rows        Append JSON row objects.
│   └── upsert-rows        Upsert JSON row objects by key.
│
├── 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

Relationship guide:

• Use workbook for file-level creation, upload/import, and manifest checks.
• Use worksheet for tab lifecycle operations.
• Use range for coordinate-based reads and writes.
• Use table when data is row-object shaped and keyed by headers.
• Use row and column for structural row/column changes.
• Use formula when preserving or changing formulas matters.
• Use style for layout operations like freeze panes, filter ranges, widths, and heights.
• Use history for read-only version inspection.
• Use file for export/list/search file operations.
• Use share for visibility and collaborator access.
• Use raw post only when a first-class command does not exist yet.

Targeting notes:

• Most commands accept --doc-id, --url, or --uri.
• Prefer --worksheet-name when the backend route supports names.
• Use --gid for gid-specific table operations; live verification showed table upsert-rows is safest with --gid.

Input Rules

• Use --doc-id, --url, or --uri to identify a workbook.
• Use --worksheet-name when the endpoint supports it.
• 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