maybeai-sheet-cli 0.3.2

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

Commands

The preferred command groups are workbook, worksheet, range, table, formula, 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.
│
├── range
│   ├── read               Read a bounded A1 range.
│   ├── write              Write a JSON matrix into an A1 range.
│   └── clear              Clear an A1 range.
│
├── table
│   ├── headers            Read header row metadata.
│   ├── append-rows        Append JSON row objects.
│   └── upsert-rows        Upsert JSON row objects by key.
│
├── 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.
│
├── 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 formula when preserving or changing formulas matters.
• 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