Maybeai Sheet Cli Skill

SKILL.md

---
name: maybeai-sheet-cli
version: 0.11.2
description: Use when the user works with MaybeAI spreadsheets through the mbs CLI, workbook doc IDs or URLs, worksheet/range/table operations, Excel import/export, SheetTable/PG imports, formulas, lineage, styles, sharing permissions, or SQL-over-sheet reports. Use sheet-dashboard for chart-heavy dashboard design.
metadata:
  openclaw:
    requires:
      env:
        - MAYBEAI_API_TOKEN
    primaryEnv: MAYBEAI_API_TOKEN
    emoji: "📊"
    homepage: https://github.com/OmniMCP-AI/maybeai-uni
---

# MaybeAI Sheet CLI

Execute spreadsheet work through `mbs`, the console script from
`maybeai-sheet-cli`. Use first-class object commands.

For local
`.xlsx` imports, choose the engine per worksheet when a workbook mixes large
table-like sheets and Excel-layout sheets. The workbook import commands support
`--engine auto`, `--engine postgres`, and comma-separated worksheet engine lists.

**Prerequisites:** `MAYBEAI_API_TOKEN`, `mbs` (`pip install maybeai-sheet-cli`)

## Quick start

```bash
# Inspect before writing
mbs workbook metadata --doc-id <DOC_ID>
mbs workbook list-worksheets --doc-id <DOC_ID> --output table

# Read and write cells/ranges
mbs excel-worksheet read --doc-id <DOC_ID> --worksheet-name Sheet1 --output table
mbs excel-worksheet read --doc-id <DOC_ID> --worksheet-name Sheet1 --range A1:D20 --output table
mbs excel-worksheet range write --doc-id <DOC_ID> --worksheet-name Sheet1 --range A1:C3 --values values.json --verify

# Work with table-shaped data
mbs excel-worksheet list-table --doc-id <DOC_ID> --gid <GID> --output json
mbs excel-table sample --doc-id <DOC_ID> --worksheet-name Orders --table-id 1 --limit 20 --output table
mbs db-table sample --doc-id <DOC_ID> --name orders_large --limit 20 --output table
mbs db-table create --doc-id <DOC_ID> --name Orders --rows orders.json
mbs db-table create --doc-id <DOC_ID> --name Orders --columns columns.json --rows rows.json --if-exists adopt --verify
mbs db-table insert --doc-id <DOC_ID> --name Orders --rows new_orders.json

# Import files
mbs workbook import-plan ./mixed-workbook.xlsx --engine auto --output table
mbs workbook import ./report.xlsx
mbs workbook import ./mixed-workbook.xlsx --engine auto
mbs workbook import ./mixed-workbook.xlsx --engine "postgres,excel,excel,postgres"
mbs workbook import ./large-table.xlsx --engine postgres
mbs workbook --doc-id <DOC_ID> copy --title "Copy of Workbook"

# Formulas and sharing
mbs excel-worksheet range set-formula --doc-id <DOC_ID> --worksheet-name Model --cell E2 --formula '=SUM(B2:D2)'
mbs excel-worksheet range set-formula --doc-id <DOC_ID> --operations formulas.json --recalculate-mode worksheet
mbs db-table range set-formula --doc-id <DOC_ID> --name orders_large --cell G2 --formula '=SQL("select * from orders_large limit 10")'
mbs workbook calculate --doc-id <DOC_ID>
mbs excel-worksheet calculate --doc-id <DOC_ID> --worksheet-name Model
mbs excel-worksheet range calculate --doc-id <DOC_ID> --worksheet-name Model --cell E2 --formula '=SUM(B2:D2)'
mbs share permission --doc-id <DOC_ID>
```

- `--output table` for human inspection; `json` (default) for automation
- Use `--base-url http://localhost:7011` or `MAYBEAI_BASE_URL=http://localhost:7011` for the local `play-be` router; `localhost:3003` is the chat frontend, not the spreadsheet API backend
- Targeting flags (`--doc-id`, `--gid`, `--worksheet-name`, `--output`) work at root, group, or command level
- Always pass a leaf subcommand (`read`, `metadata`, `insert`, etc.)

Command catalog: [references/cli-commands.md](references/cli-commands.md)

## Execution order

1. `mbs <group> <command> --help` when flags are unclear
2. [references/cli-commands.md](references/cli-commands.md) for command lookup
3. Topic reference below for semantics, edge cases, and uncovered CLI gaps

## Critical rules

**Worksheet targeting.** Non-first worksheets MUST be named explicitly. Prefer `--worksheet-name` for current object commands; use `--gid` mainly for legacy `sheet` aliases. Without either, calls often hit the first worksheet. Details: [references/read-write.md](references/read-write.md)

**Metadata-first.** Before reads or writes on an unfamiliar workbook: `workbook metadata` or `workbook list-worksheets`, then pick worksheet/gid/table.

**Worksheet table detection.** Use `excel-worksheet list-table --gid <GID>` when a visual Excel worksheet can contain multiple separated tables. The routed local path is `play-be` on port `7011`, and Excelize-backed worksheets should return content-backed table ranges such as `A4:I16` and `A20:I27` instead of one whole-sheet range.

**Import engine choice.** Use `mbs workbook import-plan ./file.xlsx --engine auto` before importing unfamiliar workbooks. Use `--engine auto` for mixed or unknown files. Use `--engine postgres` only for known single-table, flat datasets where each data column has one datatype except the header and missing values. Use `--engine excelize` for reports, summaries, dashboards, formatted workbooks, formulas/merged cells, and worksheets with multiple separated tables. Explicit Postgres is strict: if a worksheet such as `L1_广州瑞鹏_详细` contains two tables in one worksheet, PG should fail with `PG_IMPORT_UNSUPPORTED_LAYOUT`; auto mode may fallback to Excelize and report that fallback. Verify the import response and `workbook list-worksheets` report the final engine per worksheet. Details: [references/file-management.md](references/file-management.md)

**Object model.** Use `excel-worksheet read` for full worksheet reads and bounded `--range` reads. Use `excel-worksheet range` for coordinate writes, clears, searches, formula persistence, and one-off formula calculation; `excel-table` for worksheet-backed Excelize tables; `db-table` for PG/SheetTable-backed tables; `db-table range` for PG-backed formula writes; `formula` for formula reads, workbook-level batch writes, and lineage; `workbook calculate` or `excel-worksheet calculate` for recalculation; and `share` for access.

**Write priority.** `db-table create` for a new PG/SheetTable-backed table from JSON row objects; `excel-table insert` or `db-table insert` for appending rows to existing tables; `excel-worksheet range write` for exact cells; legacy `sheet append/upsert` only when you need the compatibility path.

**Range value mode.** `excel-worksheet range write` uses backend RAW value handling: numeric-looking strings such as `"5.53%"` and `"9,007,000"` remain strings. Treat USER_ENTERED parsing as unavailable unless a specific command exposes it.

**Verify after every write.** Use `--verify` where available, then `excel-worksheet read --output table`, `excel-table sample`, `db-table sample`, or `workbook list-worksheets`.

**DB table lifecycle.** `db-table create` is API-backed and infers columns from JSON row objects unless `--columns columns.json` is provided. Use `--if-exists adopt` or `--adopt-existing` only when a matching PG table may already exist, and pair it with `--verify` so the CLI confirms `workbook list-worksheets` reports a PG/SheetTable-backed registry entry. `db-table update` and `db-table delete` are still planned stubs; do not claim they can mutate data until `mbs db-table update --help` or `mbs db-table delete --help` shows a real backend route.

**Styles.** Use first-class `excel-worksheet style` commands for freeze panes, filters, widths, heights, cell style batches, gridlines, filter values, conditional formats, and worksheet style planning/apply. See [references/charts-formatting.md](references/charts-formatting.md).

**SQL.** Prefer live `=SQL(...)` formulas written through `mbs excel-worksheet range set-formula`. Static SQL result-sheet writes are not currently documented as a supported CLI workflow unless a first-class command appears in `mbs --help`. See [references/formulas-sql.md](references/formulas-sql.md).

## Task routing

| Task | Start here |
|------|------------|
| Command flags and examples | [references/cli-commands.md](references/cli-commands.md) |
| Read/write targeting and API choice | [references/read-write.md](references/read-write.md) |
| Upload, export, sharing | [references/file-management.md](references/file-management.md) |
| Workbook semantic overview | [references/workbook-profile.md](references/workbook-profile.md) |
| Sharing and permissions | [references/permission-sharing.md](references/permission-sharing.md) |
| Formulas and SQL result sheets | [references/formulas-sql.md](references/formulas-sql.md) |
| Formula dependency tracing | [references/lineage-trace.md](references/lineage-trace.md) |
| Charts, freeze panes, styles | [references/charts-formatting.md](references/charts-formatting.md) |
| Failures and recovery | [references/errors-recovery.md](references/errors-recovery.md) |
| Clickable cell refs in answers | [references/clickable-refs.md](references/clickable-refs.md) |
| Live `=SQL(...)` showcase | [references/sql-formula-showcase.md](references/sql-formula-showcase.md) |

## Workflows

### Inspect a workbook

```
- [ ] workbook metadata or workbook list-worksheets
- [ ] identify worksheet name, table id, or db-table name
- [ ] read sample with --output table
```

```bash
mbs workbook metadata --doc-id <DOC_ID>
mbs workbook list-worksheets --doc-id <DOC_ID> --output table
mbs excel-worksheet read --doc-id <DOC_ID> --worksheet-name <SHEET> --output table
mbs excel-worksheet read --doc-id <DOC_ID> --worksheet-name <SHEET> --range A1:D20 --output table
```

### Upload and inspect

```
- [ ] workbook import
- [ ] capture document_id from JSON output
- [ ] workbook list-worksheets -> table sample
```

```bash
# Small workbook-style files
mbs workbook import-plan ./file.xlsx --engine auto --output table
mbs workbook import ./file.xlsx
mbs workbook metadata --doc-id <DOC_ID>
mbs workbook list-worksheets --doc-id <DOC_ID> --output table

# Large table-like files
mbs workbook import ./file.xlsx --engine postgres
mbs db-table sample --doc-id <DOC_ID> --name <TABLE_NAME> --limit 20 --output table
```

See [references/file-management.md](references/file-management.md) for engine choice and PG verification.

### Sync rows by key

```
- [ ] confirm key column name
- [ ] use legacy sheet upsert when key-based merge is required
- [ ] recalculate if downstream formulas exist
- [ ] read back target range
```

```bash
mbs sheet upsert --doc-id <DOC_ID> --gid <GID> --key order_id --rows rows.json --verify
mbs excel-worksheet calculate --doc-id <DOC_ID> --worksheet-name <SHEET>
```

### SQL result sheet

```
- [ ] headers + read sample on source sheet
- [ ] write a live =SQL(...) formula
- [ ] read result sheet
```

See [references/formulas-sql.md](references/formulas-sql.md).

### Trace formula lineage

```bash
mbs formula lineage --doc-id <DOC_ID> --worksheet-name <SHEET> --cell E2 --format tree --output yaml
```

See [references/lineage-trace.md](references/lineage-trace.md) for response interpretation.

### Share or check access

```bash
mbs share permission --doc-id <DOC_ID>
mbs share visibility --doc-id <DOC_ID> --visibility public --public-permission viewer
# Share read-only access with a MaybeAI user email
mbs share grant --doc-id <DOC_ID> --email user@example.com --permission viewer
# Share write/edit access with a MaybeAI user email
mbs share grant --doc-id <DOC_ID> --email user@example.com --permission editor
mbs share list --doc-id <DOC_ID>
```

See [references/permission-sharing.md](references/permission-sharing.md) for owner requirements and access rules.

## Boundaries

- **Dashboard/chart layout** -> use `sheet-dashboard`, not this skill
- **Uncovered CLI gaps** -> check current `mbs --help` for a supported command
- **Clickable refs** -> only confirmed locations; see [references/clickable-refs.md](references/clickable-refs.md)