Maybeai Sheet Cli Skill

Use when the user works with MaybeAI spreadsheets through the mbs CLI for workbook inspection, import/export, worksheet/range/table writes, formulas, worksheet styling, chart/image CRUD, dashboard validate/refresh flows, or sharing. Route dashboard design and chart composition to sheet-dashboard.

Wade Deng@no7dw

Install

openclaw skills install @no7dw/maybeai-sheet-cli-skill

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 check-error --doc-id <DOC_ID> --worksheet-name Model
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 create-from-range --doc-id <TARGET_DOC_ID> --name R_OrderLines_Store1 --source-doc-id <SOURCE_DOC_ID> --worksheet-name "1店" --range A2:AR423 --header-row 0 --use-header-names --if-exists adopt --verify
mbs db-table create-from-query --doc-id <DOC_ID> --worksheet-name Orders --name OrderSummary --sql-file order_summary.sql --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>
mbs excel-worksheet chart list --doc-id <DOC_ID> --worksheet-name Dashboard
mbs excel-worksheet image list --doc-id <DOC_ID> --worksheet-name Dashboard
mbs excel-worksheet dashboard validate --spec dashboard.json
mbs excel-worksheet dashboard refresh --doc-id <DOC_ID> --spec dashboard.json
mbs excel-worksheet dashboard manifest --doc-id <DOC_ID> --worksheet-name Dashboard

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

Execution order

mbs <group> <command> --help when flags are unclear
references/cli-commands.md for command lookup
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

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

Object model. Use excel-worksheet read for full worksheet reads and bounded --range reads. Use excel-worksheet check-error to scan worksheet readback for formula-style error values and empty cached formula results. 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-from-range for cross-document raw R_* surfaces from a source worksheet range; db-table create-from-query for SQL-materialized PG/SheetTable handoff tables; 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. After formula writes, recalculation, or SQL/report-sheet updates, also run excel-worksheet check-error on the worksheet before claiming success. Add --range only when you intentionally want to isolate one output block.

DB table lifecycle. db-table create-from-range is API-backed and CLI-composed for raw-surface import: it reads a source worksheet range via /api/v1/excel/read_sheet, reshapes the values matrix (--header-row is 0-based inside that matrix; --use-header-names keeps semantic headers, otherwise raw_col_NNN), drops blank rows, then creates a PG/SheetTable on the target --doc-id. Prefer it over inventing per-run Python import drivers. For merged-title sheets, start --range at the semantic header row (for example A2:...) and keep --header-row 0. db-table create-from-query is API-backed and CLI-composed: it sends the SQL as =SQL(...) through /api/v1/excel/calc-formula, parses the returned table-shaped values / range_values, then calls /api/v1/excel/db_table/create. After the final table exists, current CLI versions try to persist the same source SQL formula into the final table cell, defaulting to A1, and return context.formula_trace with persisted, failed, skipped, or disabled status. Use it for medallion handoff tables such as S_OrderDetailsStructureInput / S1_* when the source tables already exist in MaybeSheet. For user-facing silver handoffs, A1 must remain =SQL(...). Inspect formula_trace; if status is not persisted, or formula read / excel-worksheet read --range A1 shows only a header value (for example period), immediately run mbs db-table range set-formula --name <table> --cell A1 --formula '=SQL("...")' and re-verify. Do not use --no-preserve-formula on those handoff tables. db-table create 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. excel-worksheet copy --target-doc-id fails fast because the backend copy route is same-document only. 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.

SQL. For reusable PG/SheetTable handoff tables, prefer mbs db-table create-from-query --sql-file ... --verify; it materializes the SQL result as a named DB table. For live workbook formulas, use mbs excel-worksheet range set-formula or mbs db-table range set-formula. User-facing silver sheets such as S_OrderDetailsStructureInput must expose the generating query as A1 =SQL(...) — materialized rows alone are not enough. See references/formulas-sql.md.

bash

mbs excel-worksheet dashboard validate --spec dashboard.json
mbs excel-worksheet dashboard refresh --doc-id <DOC_ID> --spec dashboard.json
mbs excel-worksheet dashboard manifest --doc-id <DOC_ID> --worksheet-name Dashboard
mbs excel-worksheet chart list --doc-id <DOC_ID> --worksheet-name Dashboard

Use dashboard create-config when the worksheet should be created from the spec in one run.

Task routing

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

Workflows

Inspect a workbook

text

- [ ] 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

text

- [ ] 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 for engine choice and PG verification.

Sync rows by key

text

- [ ] 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

text

- [ ] headers + read sample on source sheet
- [ ] write a live =SQL(...) formula
- [ ] read result sheet
- [ ] scan the worksheet with `excel-worksheet check-error`

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