Metadata-Version: 2.4
Name: maybeai-sheet-cli
Version: 0.6.0
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.

List user-visible workbooks:

```bash
mbs workbook list-user-workbooks --limit 20
```

Read a worksheet:

```bash
mbs excel-worksheet read --doc-id abc123 --worksheet-name Sheet1
mbs excel-worksheet read --doc-id abc123 --worksheet-name Sheet1 --range A1:H1
```

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
```

Import a mixed workbook and let the backend select engines per worksheet:

```bash
mbs workbook import ./mixed-workbook.xlsx --engine auto
mbs workbook import ./mixed-workbook.xlsx --engine "postgres,excel,excel,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`.


## 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`. 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
│   ├── read                     API   Read the full range of the 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                   PLAN  Create a PG-backed table from JSON row data.
│   ├── update                   PLAN  Update PG-backed rows from JSON row data.
│   ├── delete                   PLAN  Delete PG-backed rows/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.
```

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 read --doc-id abc123 --worksheet-name Actuals  # API
mbs excel-worksheet read --doc-id abc123 --worksheet-name Actuals --range A1:D20  # API
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, advanced structured alias
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 100 --offset 200  # API
mbs db-table insert --doc-id abc123 --name orders-large --rows rows.json  # API
mbs db-table create --doc-id abc123 --name Orders --rows orders.json  # PLAN
mbs db-table update --doc-id abc123 --name Orders --key order_id --rows orders_patch.json  # PLAN
mbs db-table update --doc-id abc123 --name Orders --row-index 42 --rows row_patch.json  # PLAN
mbs db-table update --doc-id abc123 --name Orders --where '{"status":"open"}' --rows status_patch.json  # PLAN
mbs db-table update --doc-id abc123 --name Orders --column-index 3 --column-name status  # PLAN
mbs db-table delete --doc-id abc123 --name Orders --where '{"order_id":"A1"}' --yes  # PLAN
mbs db-table delete --doc-id abc123 --name Orders --row-index 42 --count 10 --yes  # PLAN
mbs db-table delete --doc-id abc123 --name Orders --column-index 3 --yes  # PLAN
mbs db-table delete --doc-id abc123 --name Orders --column-name status --yes  # PLAN

# 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
```

`db-table read`, `schema`, and `sample` keep reads bounded. The default read
limit is 100 rows, and `--limit` / `--offset` are capped at 10,000 to avoid
accidental large PG scans. Use a keyset-style backend contract for deeper
pagination when it becomes available.

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 read` for full worksheet used-range inspection.
- Use `excel-worksheet` for Excel tab lifecycle operations.
- 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 when a route specifically requires gid targeting.

## 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
```
