maybeai-sheet-cli-skill-publish-apx-fz1w

原始内容

---
name: maybeai-sheet-cli
version: 0.19.0
description: Use when the user works with MaybeAI spreadsheets through the mbs CLI for workbook inspection, local or remote-URL file import, native cross-workbook import/export, worksheet/range/table writes, full worksheet data refreshes that keep headers, formulas, worksheet styling, chart/image CRUD, dashboard validate/refresh/export-template flows, or sharing. Route dashboard design and chart composition to `sheet-dashboard`.
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 `.xls` / `.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 base`, and
comma-separated worksheet engine lists. CSV/TSV files and public Google Sheet
URLs use the import-source preview flow and can import as a new workbook or
append all or selected worksheets/tabs to an existing workbook. Remote HTTPS
Excel URLs create a new workbook through `/api/v1/excel/import_by_url`.
To migrate one existing Sheet-backed worksheet to Base, use the guarded
`worksheet convert-to-base` workflow below; it is a one-way data migration,
not an import-engine setting.

**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
mbs sheet update-data-keep-headers --doc-id <DOC_ID> --worksheet-name Sheet1 --data rows.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 metadata --doc-id <DOC_ID> --name orders_large --include-headers --output json
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
mbs db-table field metadata --doc-id <DOC_ID> --name orders_large --output json
mbs db-table field batch-update --doc-id <DOC_ID> --name orders_large --updates field-updates.json --verify

# 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 "base,sheet,sheet,base"
mbs workbook import ./large-table.xlsx --engine base
mbs workbook import "https://static.example.com/imports/report.xlsx" --engine auto
mbs workbook import "https://static.example.com/download?id=123" --source-type xlsx --filename report.xlsx --engine sheet
mbs workbook import ./orders.csv --engine base
mbs workbook import ./orders.tsv --engine sheet
mbs workbook import "https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/edit#gid=0" --engine base
mbs worksheet import ./report.xlsx --strategy create --doc-id <TARGET_DOC_ID> --engine base --verify
mbs worksheet import ./report.xlsx --strategy create --doc-id <TARGET_DOC_ID> --source-worksheet-name "联盟" --target-worksheet-name "联盟导入" --engine base --verify
mbs worksheet import ./report.xlsx --strategy create --doc-id <TARGET_DOC_ID> --source-worksheet-name "联盟" --source-worksheet-name "订单" --engine base --verify
mbs worksheet import ./orders.csv --strategy create --doc-id <TARGET_DOC_ID> --engine base --verify
mbs worksheet import ./orders.csv --strategy create --doc-id <TARGET_DOC_ID> --source-worksheet-name orders --target-worksheet-name Orders --engine base --verify
mbs worksheet import ./orders.csv --strategy create --doc-id <TARGET_DOC_ID> --source-worksheet-name orders --source-worksheet-name refunds --engine base --verify
mbs worksheet import "https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/edit#gid=0" --strategy create --doc-id <TARGET_DOC_ID> --engine sheet --verify
mbs worksheet import "https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/edit#gid=0" --strategy create --doc-id <TARGET_DOC_ID> --source-worksheet-name "1店" --target-worksheet-name "Store 1" --engine sheet --verify
mbs worksheet import "https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/edit#gid=0" --strategy create --doc-id <TARGET_DOC_ID> --source-worksheet-name "1店" --source-worksheet-name "2店" --engine sheet --verify
mbs worksheet import ./rows.json --strategy replace --doc-id <TARGET_DOC_ID> --worksheet-name Students --verify
mbs worksheet import --strategy create --doc-id <TARGET_DOC_ID> --source-doc-id <SOURCE_DOC_ID> --source-worksheet-name "1店" --verify
mbs worksheet import --strategy create --doc-id <TARGET_DOC_ID> --source-doc-id <SOURCE_DOC_ID> --source-worksheet-name "1店" --source-worksheet-name "2店" --verify
mbs worksheet import --strategy create --transfer-mode native --doc-id <TARGET_DOC_ID> --source-doc-id <SOURCE_DOC_ID> --source-worksheet-name "工作表3" --source-worksheet-name "工作簿1" --verify
# Convert one existing Sheet worksheet to Base: dry-run first, then confirm.
mbs worksheet convert-to-base --doc-id <DOC_ID> --worksheet-name Orders --dry-run
mbs worksheet convert-to-base --doc-id <DOC_ID> --gid <GID> --yes --verify
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 image set --doc-id <DOC_ID> --worksheet-name Dashboard --old-cell B3 --cell B3 --format picture-format.json --width 120 --height 91
mbs excel-worksheet media check --doc-id <DOC_ID> --worksheet-name Dashboard
mbs style beautify --doc-id <DOC_ID> --worksheet-name Sheet1 --dry-run --output json
mbs style beautify --doc-id <DOC_ID> --worksheet-name Sheet1 --output json
mbs pivot preview --doc-id <DOC_ID> --worksheet-name SourceData --spec artifacts/pivot-config.json
mbs pivot upsert --doc-id <DOC_ID> --target-worksheet-name PivotResult --anchor-cell A1 --spec pivot-config.json
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 dashboard export-template --doc-id <DOC_ID> --worksheet-name Dashboard --template-id <template-id> --out-dir <analysis-style-system-skill-dir>/dashboard-templates/<template-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. Run `mbs --version` and `mbs --help` once at the start of a session; trust the local CLI over remembered examples.
2. `mbs <group> <command> --help` when flags are unclear.
3. [references/cli-commands.md](references/cli-commands.md) for command lookup.
4. 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 Sheet-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 creating a new workbook from an unfamiliar local Excel file. Use `mbs workbook import` only to create a new workbook. To import into an existing workbook, use `mbs worksheet import --strategy create`; omit `--source-worksheet-name` to import all source worksheets/tabs, repeat it to select multiple sources, and use `--target-worksheet-name` only for one selected source. Use `--engine base` only for known flat tables and `--engine sheet` for reports, formulas, merged cells, styles, or multiple separated tables. For Maybe Sheet-to-Maybe Sheet imports, use `--transfer-mode values` for Base raw surfaces and `--transfer-mode native` to preserve registered engines and supported fidelity. Native transfer rejects `--engine`. Details: [references/file-management.md](references/file-management.md)

**Worksheet engine migration.** To migrate an existing Sheet-backed worksheet to Base, inspect `workbook list-worksheets` first and target exactly one worksheet with `--gid` or `--worksheet-name` (a URL containing `gid` may supply it). Run `mbs worksheet convert-to-base ... --dry-run`, then rerun with `--yes --verify`. This is one-way: no Base-to-Sheet CLI/backend conversion exists. It removes the old Sheet-engine cell content by default while retaining styles; pass `--keep-sheet-source` only when that source content must remain. `--dry-run` and `--verify` cannot be combined. Details: [references/read-write.md](references/read-write.md)

**Dashboard imports.** For chart-heavy dashboards, plan the workbook before upload. Data source worksheets that will be queried by chart SQL should be Base-compatible flat tables and usually use `base`; cover, summary, and dashboard canvas worksheets should usually use `sheet`. Use the worksheet-index engine list only after `import-plan` confirms sheet order.

**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 Sheet-backed worksheet tables; `db-table` for Base-backed tables; `db-table range` for Base-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 Base-backed handoff tables; `db-table create` for a new Base-backed table from JSON row objects; `excel-table insert` or `db-table insert` for appending rows to existing tables; `sheet update-data-keep-headers` for replacing all data rows while preserving row 1, header order, styles, and formula columns; `excel-worksheet range write` for exact cells; legacy `sheet append/upsert` only when you need the compatibility path.

**Full worksheet data refresh.** Prefer the unified entry point: `mbs worksheet import ./rows.json --strategy replace --doc-id <DOC_ID> --worksheet-name <SHEET> --verify`. It uses the same `/api/v1/excel/update_data_keep_headers` contract as `mbs sheet update-data-keep-headers`. The JSON file must be a non-empty array of objects whose keys match existing headers. The command keeps row 1 and column order, rejects unknown keys, preserves formula columns and recalculates by default, and rejects `--dry-run --verify`. Use `--dry-run` first for unfamiliar data. Details: [references/read-write.md](references/read-write.md)

**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. For `worksheet import` into raw Base-backed db-table surfaces, successful stdout plus `--verify` is already the existence proof; do not loop over every created table.

**DB table metadata and headers.** `db-table metadata` is a single-table lookup; pass `--name` or `--backend-id`. Add `--include-headers` when the agent needs header text in the final JSON. Current CLI versions resolve the table through `/api/v1/excel/worksheet/metadata`, merge targeted `/api/v1/excel/worksheet/dimensions`, and return `headers`, `header_names`, and header metadata when available. Do not expect `workbook metadata` to include exact table headers.

**DB table field style.** For Base-backed column formatter, color, background, width, or beautified header style, prefer `mbs db-table field batch-update --updates field-updates.json --verify` over per-column loops. Use `mbs db-table field metadata` before explicit updates and `mbs excel-worksheet read --output json` after updates to confirm `formatting.frozen_rows`, `formatting.auto_filter`, and `db_table.fields[*].property`. Plain Base-backed db-table reads should get freeze/filter config from the backend; frontend defaults are not the source of truth.

**DB table lifecycle.** `db-table create-from-range` is API-backed and CLI-composed for raw-surface import. `db-table create-from-query` materializes SQL results and records formula trace status. Use `--if-exists adopt` only with `--verify`. For supported cross-document worksheet copies, use `mbs worksheet import --strategy create --transfer-mode native`; do not use the legacy workbook-import native entry point.

**Styles.** Use `mbs style beautify` for agent-friendly report/table polish. It reads metadata first, classifies columns from Chinese/English headers plus sample values, applies Excel worksheet styles, and writes Base-backed field style metadata through the batch route when possible. Use first-class `excel-worksheet style` commands for explicit 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).

**Images.** Worksheet images are floating objects like charts, not cell values. Before `image insert`, confirm the target worksheet is Sheet-backed with `workbook list-worksheets`; Base-only worksheets do not support `add_picture`. Use `image insert` / `image set` with chart-compatible picture `format` JSON for position and size (`from`, `to`, and pixel offsets), then verify with `image list` and `media check`. Do not treat the returned `cell` as enough to preserve layout after drag/resize. To create a new image canvas in an existing Base Mode workbook, import a small blank `.xlsx` with `--engine sheet` instead of `excel-worksheet create`.

**SQL.** For reusable Base-backed 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 `OrderDetailsStructureInput` must expose the generating query as `A1 =SQL(...)` — materialized rows alone are not enough. See [references/formulas-sql.md](references/formulas-sql.md).

**Pivot tables.** Use first-class `mbs pivot read`, `mbs pivot preview`, `mbs pivot upsert`, and `mbs pivot delete`. Do not call `/api/v1/excel/pivot_table/*`, `/api/v1/excel/read_pivot_table`, legacy `/api/pivot_table/*`, or hand-build `MAYBE_PIVOT` formulas through `raw post` / `formula set` unless the local `mbs pivot --help` proves the command is unavailable. `pivot upsert` requires an explicit target anchor cell; if the user says `A1`, keep `--anchor-cell A1`. Details and spec examples: [references/pivot-tables.md](references/pivot-tables.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
mbs excel-worksheet dashboard export-template --doc-id <DOC_ID> --worksheet-name Dashboard --template-id <template-id> --out-dir <analysis-style-system-skill-dir>/dashboard-templates/<template-id> --force
```

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

For dashboard specs with `chart.type: "html"`, the chart object must include non-empty `chart.html`, `chart.sql`, `chart.format.from/to`, and `chart.dimension`. Named sources must be direct SQL strings such as `"data_sources": {"mgmt_summary": "SELECT * FROM \"gid_2\""}`; never emit `"mgmt_summary": {"sql": "..."}`. For large renderer dependencies, reference approved CDN packages with `<script src>` such as jsdelivr/unpkg/cdnjs/d3js; do not inline full ECharts/D3 bundles into `chart.html`.

For dashboard render proof, prefer:

```bash
mbs excel-worksheet dashboard render-probe \
  --doc-id <DOC_ID> \
  --worksheet-name <DASHBOARD_WORKSHEET> \
  --chart-id <HTML_CHART_ID> \
  --text-marker <TITLE_OR_KPI> \
  --data-marker <DATA_VALUE> \
  --screenshot dashboard.png \
  --output json
```

Interpret render proof in tiers. `local_probe_passed` means the local HTML runtime, runtime payload adapter, DOM, and data binding worked. `screenshot_verified` means PNG screenshot capture also worked. If `visual_verification.status` is `environment_blocked` with `playwright_unavailable` or `chromium_unavailable`, install Playwright/Chromium in the running environment (`npm i -D playwright`, `npx playwright install chromium`) and retry; do not treat that as a dashboard spec failure.


```bash
mbs excel-worksheet dashboard validate --spec dashboard.json
mbs excel-worksheet dashboard refresh --doc-id <DOC_ID> --spec dashboard.json --dry-run
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
mbs excel-worksheet dashboard export-template --doc-id <DOC_ID> --worksheet-name Dashboard --template-id <template-id> --out-dir <analysis-style-system-skill-dir>/dashboard-templates/<template-id> --force
```

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](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) |
| Pivot tables and pivot config specs | [references/pivot-tables.md](references/pivot-tables.md) |
| Formula dependency tracing | [references/lineage-trace.md](references/lineage-trace.md) |
| Charts, images, dashboards, worksheet styling | [references/charts-formatting.md](references/charts-formatting.md) |
| Sharing and permissions | [references/permission-sharing.md](references/permission-sharing.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
- [ ] use import stdout plus `--verify` as creation evidence
- [ ] if needed, do one representative `db-table sample --limit 2` per family
```

```bash
# Small workbook-style files
mbs workbook import-plan ./file.xlsx --engine auto --output table
mbs workbook import ./file.xlsx --verify
mbs workbook import ./orders.csv --engine base
mbs workbook import "https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/edit#gid=0" --engine sheet
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 base --verify
mbs db-table sample --doc-id <DOC_ID> --name <REPRESENTATIVE_TABLE_NAME> --limit 2 --output table

# Cross-workbook worksheet -> raw Base-backed db-table surface import
mbs worksheet import --strategy create --doc-id <TARGET_DOC_ID> --source-doc-id <SOURCE_DOC_ID> --source-worksheet-name "1店" --verify
mbs worksheet import --strategy create --doc-id <TARGET_DOC_ID> --source-doc-id <SOURCE_DOC_ID> --source-worksheet-name "1店" --source-worksheet-name "2店" --verify

# Replace existing worksheet rows from JSON while keeping headers
mbs worksheet import ./rows.json --strategy replace --doc-id <TARGET_DOC_ID> --worksheet-name Students --verify

# Native Maybe Sheet worksheet import; engine is detected per worksheet
mbs worksheet import --strategy create --transfer-mode native --doc-id <TARGET_DOC_ID> --source-doc-id <SOURCE_DOC_ID> --source-worksheet-name "工作表3" --source-worksheet-name "工作簿1" --verify
mbs worksheet import --strategy create --transfer-mode native --doc-id <TARGET_DOC_ID> --source-doc-id <SOURCE_DOC_ID> --verify

# Append source worksheets/tabs into an existing workbook
mbs worksheet import ./file.xlsx --strategy create --doc-id <TARGET_DOC_ID> --engine sheet --verify
mbs worksheet import ./file.xlsx --strategy create --doc-id <TARGET_DOC_ID> --source-worksheet-name "联盟" --target-worksheet-name "联盟导入" --engine sheet --verify
mbs worksheet import ./file.xlsx --strategy create --doc-id <TARGET_DOC_ID> --source-worksheet-name "联盟" --source-worksheet-name "订单" --engine base --verify
mbs worksheet import ./orders.csv --strategy create --doc-id <TARGET_DOC_ID> --engine base --verify
mbs worksheet import "https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/edit#gid=0" --strategy create --doc-id <TARGET_DOC_ID> --source-worksheet-name "1店" --target-worksheet-name "Store 1" --engine sheet --verify
```

Do not follow successful raw-surface imports with per-table `schema` / `sample` / `read` loops. See [references/file-management.md](references/file-management.md) for engine choice and Base Mode verification.

### Convert a worksheet to Base

```
- [ ] inspect `workbook list-worksheets` and select exactly one Sheet-backed worksheet
- [ ] run `convert-to-base --dry-run` with `--gid` or `--worksheet-name`
- [ ] execute the reviewed conversion with `--yes --verify`
- [ ] retain old Sheet-engine source cells only when explicitly requested
```

```bash
# The workbook URL can provide both document ID and gid.
mbs worksheet convert-to-base \
  --url "https://www.maybe.ai/docs/spreadsheets/d/<DOC_ID>?gid=<GID>" \
  --dry-run

# Execute after reviewing the dry run. Source cells are scrubbed by default.
mbs worksheet convert-to-base \
  --doc-id <DOC_ID> \
  --worksheet-name Orders \
  --yes \
  --verify

# Keep the prior Sheet-engine cell content only when required.
mbs worksheet convert-to-base \
  --doc-id <DOC_ID> \
  --gid <GID> \
  --keep-sheet-source \
  --yes \
  --verify
```

Use `--recalculate` when the converted Base worksheet should recalculate
immediately. Do not combine `--dry-run` with `--verify`. The command checks
metadata during `--verify` and succeeds only when the selected worksheet
reports `data_engine: base`.

### Dashboard execution

```
- [ ] `mbs --version` and relevant `--help`
- [ ] `mbs workbook import-plan ./file.xlsx --engine auto --output table`
- [ ] import with `--engine auto` or an explicit worksheet-index engine list
- [ ] `workbook list-worksheets` verifies Data_* Base Mode and Dashboard/summary Sheet mode where intended
- [ ] `dashboard validate --spec dashboard.json`
- [ ] `dashboard refresh --dry-run` checks payload shape before mutation
- [ ] execute `dashboard refresh`; if batch errors persist, use per-chart `chart create-config`
- [ ] `dashboard manifest` and `chart list` verify persisted metadata
- [ ] read source Data_* sheets and run browser/vision verification when logged-in canvas access exists
```

See [references/charts-formatting.md](references/charts-formatting.md) for chart spec shapes, fallback, and verification limits.

### Dashboard template export

Use this only when the user wants to promote an existing Maybe Sheet HTML dashboard worksheet into a reusable template package. The dashboard canvas must be a `sheet` worksheet, and the worksheet should contain exactly one persisted `chart.type=html` dashboard chart unless `--chart-id` or `--cell` is provided.

```bash
mbs excel-worksheet dashboard export-template \
  --doc-id <DOC_ID> \
  --worksheet-name <DASHBOARD_WORKSHEET> \
  --template-id <template-id> \
  --out-dir <analysis-style-system-skill-dir>/dashboard-templates/<template-id> \
  --force
```

The command writes `template.json`, `html/dashboard.template.html`, and `html/runtime-payload.schema.json`. After export, switch to `analysis-style-system` and run `node scripts/validate_dashboard_html_template.mjs --template-dir dashboard-templates/<template-id>` before using or publishing the template skill.

### 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
- [ ] scan the worksheet with `excel-worksheet check-error`
```

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

### Pivot table

```
- [ ] inspect source worksheet headers
- [ ] author `pivot-config.json`
- [ ] preview pivot output
- [ ] upsert with explicit target worksheet and anchor cell
- [ ] read target range to verify
```

```bash
mbs pivot preview --doc-id <DOC_ID> --worksheet-name <SOURCE_SHEET> --spec pivot-config.json --output table
mbs pivot upsert --doc-id <DOC_ID> --target-worksheet-name PivotResult --anchor-cell A1 --spec pivot-config.json
mbs excel-worksheet read --doc-id <DOC_ID> --worksheet-name PivotResult --range A1:H30 --output table
```

See [references/pivot-tables.md](references/pivot-tables.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>
```

If `mbs share visibility` returns 403 with an owner-only message, classify it as `owner_permission_required` / `permission_skipped`. If workbook metadata already shows the requested public/editor or public/viewer visibility, report it as a share warning rather than a dashboard failure; otherwise ask the owner or service account to update visibility. 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)

name: maybeai-sheet-cli version: 0.19.0 description: Use when the user works with MaybeAI spreadsheets through the mbs CLI for workbook inspection, local or remote-URL file import, native cross-workbook import/export, worksheet/range/table writes, full worksheet data refreshes that keep headers, formulas, worksheet styling, chart/image CRUD, dashboard validate/refresh/export-template flows, or sharing. Route dashboard design and chart composition to sheet-dashboard. 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 .xls / .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 base, and comma-separated worksheet engine lists. CSV/TSV files and public Google Sheet URLs use the import-source preview flow and can import as a new workbook or append all or selected worksheets/tabs to an existing workbook. Remote HTTPS Excel URLs create a new workbook through /api/v1/excel/import_by_url. To migrate one existing Sheet-backed worksheet to Base, use the guarded worksheet convert-to-base workflow below; it is a one-way data migration, not an import-engine setting.

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

Quick start

# 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
mbs sheet update-data-keep-headers --doc-id <DOC_ID> --worksheet-name Sheet1 --data rows.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 metadata --doc-id <DOC_ID> --name orders_large --include-headers --output json
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
mbs db-table field metadata --doc-id <DOC_ID> --name orders_large --output json
mbs db-table field batch-update --doc-id <DOC_ID> --name orders_large --updates field-updates.json --verify

# 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 "base,sheet,sheet,base"
mbs workbook import ./large-table.xlsx --engine base
mbs workbook import "https://static.example.com/imports/report.xlsx" --engine auto
mbs workbook import "https://static.example.com/download?id=123" --source-type xlsx --filename report.xlsx --engine sheet
mbs workbook import ./orders.csv --engine base
mbs workbook import ./orders.tsv --engine sheet
mbs workbook import "https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/edit#gid=0" --engine base
mbs worksheet import ./report.xlsx --strategy create --doc-id <TARGET_DOC_ID> --engine base --verify
mbs worksheet import ./report.xlsx --strategy create --doc-id <TARGET_DOC_ID> --source-worksheet-name "联盟" --target-worksheet-name "联盟导入" --engine base --verify
mbs worksheet import ./report.xlsx --strategy create --doc-id <TARGET_DOC_ID> --source-worksheet-name "联盟" --source-worksheet-name "订单" --engine base --verify
mbs worksheet import ./orders.csv --strategy create --doc-id <TARGET_DOC_ID> --engine base --verify
mbs worksheet import ./orders.csv --strategy create --doc-id <TARGET_DOC_ID> --source-worksheet-name orders --target-worksheet-name Orders --engine base --verify
mbs worksheet import ./orders.csv --strategy create --doc-id <TARGET_DOC_ID> --source-worksheet-name orders --source-worksheet-name refunds --engine base --verify
mbs worksheet import "https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/edit#gid=0" --strategy create --doc-id <TARGET_DOC_ID> --engine sheet --verify
mbs worksheet import "https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/edit#gid=0" --strategy create --doc-id <TARGET_DOC_ID> --source-worksheet-name "1店" --target-worksheet-name "Store 1" --engine sheet --verify
mbs worksheet import "https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/edit#gid=0" --strategy create --doc-id <TARGET_DOC_ID> --source-worksheet-name "1店" --source-worksheet-name "2店" --engine sheet --verify
mbs worksheet import ./rows.json --strategy replace --doc-id <TARGET_DOC_ID> --worksheet-name Students --verify
mbs worksheet import --strategy create --doc-id <TARGET_DOC_ID> --source-doc-id <SOURCE_DOC_ID> --source-worksheet-name "1店" --verify
mbs worksheet import --strategy create --doc-id <TARGET_DOC_ID> --source-doc-id <SOURCE_DOC_ID> --source-worksheet-name "1店" --source-worksheet-name "2店" --verify
mbs worksheet import --strategy create --transfer-mode native --doc-id <TARGET_DOC_ID> --source-doc-id <SOURCE_DOC_ID> --source-worksheet-name "工作表3" --source-worksheet-name "工作簿1" --verify
# Convert one existing Sheet worksheet to Base: dry-run first, then confirm.
mbs worksheet convert-to-base --doc-id <DOC_ID> --worksheet-name Orders --dry-run
mbs worksheet convert-to-base --doc-id <DOC_ID> --gid <GID> --yes --verify
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 image set --doc-id <DOC_ID> --worksheet-name Dashboard --old-cell B3 --cell B3 --format picture-format.json --width 120 --height 91
mbs excel-worksheet media check --doc-id <DOC_ID> --worksheet-name Dashboard
mbs style beautify --doc-id <DOC_ID> --worksheet-name Sheet1 --dry-run --output json
mbs style beautify --doc-id <DOC_ID> --worksheet-name Sheet1 --output json
mbs pivot preview --doc-id <DOC_ID> --worksheet-name SourceData --spec artifacts/pivot-config.json
mbs pivot upsert --doc-id <DOC_ID> --target-worksheet-name PivotResult --anchor-cell A1 --spec pivot-config.json
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 dashboard export-template --doc-id <DOC_ID> --worksheet-name Dashboard --template-id <template-id> --out-dir <analysis-style-system-skill-dir>/dashboard-templates/<template-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

Execution order

Run mbs --version and mbs --help once at the start of a session; trust the local CLI over remembered examples.
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 Sheet-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 creating a new workbook from an unfamiliar local Excel file. Use mbs workbook import only to create a new workbook. To import into an existing workbook, use mbs worksheet import --strategy create; omit --source-worksheet-name to import all source worksheets/tabs, repeat it to select multiple sources, and use --target-worksheet-name only for one selected source. Use --engine base only for known flat tables and --engine sheet for reports, formulas, merged cells, styles, or multiple separated tables. For Maybe Sheet-to-Maybe Sheet imports, use --transfer-mode values for Base raw surfaces and --transfer-mode native to preserve registered engines and supported fidelity. Native transfer rejects --engine. Details: references/file-management.md

Worksheet engine migration. To migrate an existing Sheet-backed worksheet to Base, inspect workbook list-worksheets first and target exactly one worksheet with --gid or --worksheet-name (a URL containing gid may supply it). Run mbs worksheet convert-to-base ... --dry-run, then rerun with --yes --verify. This is one-way: no Base-to-Sheet CLI/backend conversion exists. It removes the old Sheet-engine cell content by default while retaining styles; pass --keep-sheet-source only when that source content must remain. --dry-run and --verify cannot be combined. Details: references/read-write.md

Dashboard imports. For chart-heavy dashboards, plan the workbook before upload. Data source worksheets that will be queried by chart SQL should be Base-compatible flat tables and usually use base; cover, summary, and dashboard canvas worksheets should usually use sheet. Use the worksheet-index engine list only after import-plan confirms sheet order.

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 Sheet-backed worksheet tables; db-table for Base-backed tables; db-table range for Base-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 Base-backed handoff tables; db-table create for a new Base-backed table from JSON row objects; excel-table insert or db-table insert for appending rows to existing tables; sheet update-data-keep-headers for replacing all data rows while preserving row 1, header order, styles, and formula columns; excel-worksheet range write for exact cells; legacy sheet append/upsert only when you need the compatibility path.

Full worksheet data refresh. Prefer the unified entry point: mbs worksheet import ./rows.json --strategy replace --doc-id <DOC_ID> --worksheet-name <SHEET> --verify. It uses the same /api/v1/excel/update_data_keep_headers contract as mbs sheet update-data-keep-headers. The JSON file must be a non-empty array of objects whose keys match existing headers. The command keeps row 1 and column order, rejects unknown keys, preserves formula columns and recalculates by default, and rejects --dry-run --verify. Use --dry-run first for unfamiliar data. Details: references/read-write.md

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. For worksheet import into raw Base-backed db-table surfaces, successful stdout plus --verify is already the existence proof; do not loop over every created table.

DB table metadata and headers. db-table metadata is a single-table lookup; pass --name or --backend-id. Add --include-headers when the agent needs header text in the final JSON. Current CLI versions resolve the table through /api/v1/excel/worksheet/metadata, merge targeted /api/v1/excel/worksheet/dimensions, and return headers, header_names, and header metadata when available. Do not expect workbook metadata to include exact table headers.

DB table field style. For Base-backed column formatter, color, background, width, or beautified header style, prefer mbs db-table field batch-update --updates field-updates.json --verify over per-column loops. Use mbs db-table field metadata before explicit updates and mbs excel-worksheet read --output json after updates to confirm formatting.frozen_rows, formatting.auto_filter, and db_table.fields[*].property. Plain Base-backed db-table reads should get freeze/filter config from the backend; frontend defaults are not the source of truth.

DB table lifecycle. db-table create-from-range is API-backed and CLI-composed for raw-surface import. db-table create-from-query materializes SQL results and records formula trace status. Use --if-exists adopt only with --verify. For supported cross-document worksheet copies, use mbs worksheet import --strategy create --transfer-mode native; do not use the legacy workbook-import native entry point.

Styles. Use mbs style beautify for agent-friendly report/table polish. It reads metadata first, classifies columns from Chinese/English headers plus sample values, applies Excel worksheet styles, and writes Base-backed field style metadata through the batch route when possible. Use first-class excel-worksheet style commands for explicit freeze panes, filters, widths, heights, cell style batches, gridlines, filter values, conditional formats, and worksheet style planning/apply. See references/charts-formatting.md.

Images. Worksheet images are floating objects like charts, not cell values. Before image insert, confirm the target worksheet is Sheet-backed with workbook list-worksheets; Base-only worksheets do not support add_picture. Use image insert / image set with chart-compatible picture format JSON for position and size (from, to, and pixel offsets), then verify with image list and media check. Do not treat the returned cell as enough to preserve layout after drag/resize. To create a new image canvas in an existing Base Mode workbook, import a small blank .xlsx with --engine sheet instead of excel-worksheet create.

SQL. For reusable Base-backed 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 OrderDetailsStructureInput must expose the generating query as A1 =SQL(...) — materialized rows alone are not enough. See references/formulas-sql.md.

Pivot tables. Use first-class mbs pivot read, mbs pivot preview, mbs pivot upsert, and mbs pivot delete. Do not call /api/v1/excel/pivot_table/*, /api/v1/excel/read_pivot_table, legacy /api/pivot_table/*, or hand-build MAYBE_PIVOT formulas through raw post / formula set unless the local mbs pivot --help proves the command is unavailable. pivot upsert requires an explicit target anchor cell; if the user says A1, keep --anchor-cell A1. Details and spec examples: references/pivot-tables.md.

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
mbs excel-worksheet dashboard export-template --doc-id <DOC_ID> --worksheet-name Dashboard --template-id <template-id> --out-dir <analysis-style-system-skill-dir>/dashboard-templates/<template-id> --force

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

For dashboard specs with chart.type: "html", the chart object must include non-empty chart.html, chart.sql, chart.format.from/to, and chart.dimension. Named sources must be direct SQL strings such as "data_sources": {"mgmt_summary": "SELECT * FROM \"gid_2\""}; never emit "mgmt_summary": {"sql": "..."}. For large renderer dependencies, reference approved CDN packages with <script src> such as jsdelivr/unpkg/cdnjs/d3js; do not inline full ECharts/D3 bundles into chart.html.

For dashboard render proof, prefer:

mbs excel-worksheet dashboard render-probe \
  --doc-id <DOC_ID> \
  --worksheet-name <DASHBOARD_WORKSHEET> \
  --chart-id <HTML_CHART_ID> \
  --text-marker <TITLE_OR_KPI> \
  --data-marker <DATA_VALUE> \
  --screenshot dashboard.png \
  --output json

Interpret render proof in tiers. local_probe_passed means the local HTML runtime, runtime payload adapter, DOM, and data binding worked. screenshot_verified means PNG screenshot capture also worked. If visual_verification.status is environment_blocked with playwright_unavailable or chromium_unavailable, install Playwright/Chromium in the running environment (npm i -D playwright, npx playwright install chromium) and retry; do not treat that as a dashboard spec failure.

mbs excel-worksheet dashboard validate --spec dashboard.json
mbs excel-worksheet dashboard refresh --doc-id <DOC_ID> --spec dashboard.json --dry-run
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
mbs excel-worksheet dashboard export-template --doc-id <DOC_ID> --worksheet-name Dashboard --template-id <template-id> --out-dir <analysis-style-system-skill-dir>/dashboard-templates/<template-id> --force

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
Pivot tables and pivot config specs	references/pivot-tables.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

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

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
- [ ] use import stdout plus `--verify` as creation evidence
- [ ] if needed, do one representative `db-table sample --limit 2` per family

# Small workbook-style files
mbs workbook import-plan ./file.xlsx --engine auto --output table
mbs workbook import ./file.xlsx --verify
mbs workbook import ./orders.csv --engine base
mbs workbook import "https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/edit#gid=0" --engine sheet
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 base --verify
mbs db-table sample --doc-id <DOC_ID> --name <REPRESENTATIVE_TABLE_NAME> --limit 2 --output table

# Cross-workbook worksheet -> raw Base-backed db-table surface import
mbs worksheet import --strategy create --doc-id <TARGET_DOC_ID> --source-doc-id <SOURCE_DOC_ID> --source-worksheet-name "1店" --verify
mbs worksheet import --strategy create --doc-id <TARGET_DOC_ID> --source-doc-id <SOURCE_DOC_ID> --source-worksheet-name "1店" --source-worksheet-name "2店" --verify

# Replace existing worksheet rows from JSON while keeping headers
mbs worksheet import ./rows.json --strategy replace --doc-id <TARGET_DOC_ID> --worksheet-name Students --verify

# Native Maybe Sheet worksheet import; engine is detected per worksheet
mbs worksheet import --strategy create --transfer-mode native --doc-id <TARGET_DOC_ID> --source-doc-id <SOURCE_DOC_ID> --source-worksheet-name "工作表3" --source-worksheet-name "工作簿1" --verify
mbs worksheet import --strategy create --transfer-mode native --doc-id <TARGET_DOC_ID> --source-doc-id <SOURCE_DOC_ID> --verify

# Append source worksheets/tabs into an existing workbook
mbs worksheet import ./file.xlsx --strategy create --doc-id <TARGET_DOC_ID> --engine sheet --verify
mbs worksheet import ./file.xlsx --strategy create --doc-id <TARGET_DOC_ID> --source-worksheet-name "联盟" --target-worksheet-name "联盟导入" --engine sheet --verify
mbs worksheet import ./file.xlsx --strategy create --doc-id <TARGET_DOC_ID> --source-worksheet-name "联盟" --source-worksheet-name "订单" --engine base --verify
mbs worksheet import ./orders.csv --strategy create --doc-id <TARGET_DOC_ID> --engine base --verify
mbs worksheet import "https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/edit#gid=0" --strategy create --doc-id <TARGET_DOC_ID> --source-worksheet-name "1店" --target-worksheet-name "Store 1" --engine sheet --verify

Do not follow successful raw-surface imports with per-table schema / sample / read loops. See references/file-management.md for engine choice and Base Mode verification.

Convert a worksheet to Base

- [ ] inspect `workbook list-worksheets` and select exactly one Sheet-backed worksheet
- [ ] run `convert-to-base --dry-run` with `--gid` or `--worksheet-name`
- [ ] execute the reviewed conversion with `--yes --verify`
- [ ] retain old Sheet-engine source cells only when explicitly requested

# The workbook URL can provide both document ID and gid.
mbs worksheet convert-to-base \
  --url "https://www.maybe.ai/docs/spreadsheets/d/<DOC_ID>?gid=<GID>" \
  --dry-run

# Execute after reviewing the dry run. Source cells are scrubbed by default.
mbs worksheet convert-to-base \
  --doc-id <DOC_ID> \
  --worksheet-name Orders \
  --yes \
  --verify

# Keep the prior Sheet-engine cell content only when required.
mbs worksheet convert-to-base \
  --doc-id <DOC_ID> \
  --gid <GID> \
  --keep-sheet-source \
  --yes \
  --verify

Use --recalculate when the converted Base worksheet should recalculate immediately. Do not combine --dry-run with --verify. The command checks metadata during --verify and succeeds only when the selected worksheet reports data_engine: base.

Dashboard execution

- [ ] `mbs --version` and relevant `--help`
- [ ] `mbs workbook import-plan ./file.xlsx --engine auto --output table`
- [ ] import with `--engine auto` or an explicit worksheet-index engine list
- [ ] `workbook list-worksheets` verifies Data_* Base Mode and Dashboard/summary Sheet mode where intended
- [ ] `dashboard validate --spec dashboard.json`
- [ ] `dashboard refresh --dry-run` checks payload shape before mutation
- [ ] execute `dashboard refresh`; if batch errors persist, use per-chart `chart create-config`
- [ ] `dashboard manifest` and `chart list` verify persisted metadata
- [ ] read source Data_* sheets and run browser/vision verification when logged-in canvas access exists

See references/charts-formatting.md for chart spec shapes, fallback, and verification limits.

Dashboard template export

Use this only when the user wants to promote an existing Maybe Sheet HTML dashboard worksheet into a reusable template package. The dashboard canvas must be a sheet worksheet, and the worksheet should contain exactly one persisted chart.type=html dashboard chart unless --chart-id or --cell is provided.

mbs excel-worksheet dashboard export-template \
  --doc-id <DOC_ID> \
  --worksheet-name <DASHBOARD_WORKSHEET> \
  --template-id <template-id> \
  --out-dir <analysis-style-system-skill-dir>/dashboard-templates/<template-id> \
  --force

The command writes template.json, html/dashboard.template.html, and html/runtime-payload.schema.json. After export, switch to analysis-style-system and run node scripts/validate_dashboard_html_template.mjs --template-dir dashboard-templates/<template-id> before using or publishing the template skill.

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

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
- [ ] scan the worksheet with `excel-worksheet check-error`

See references/formulas-sql.md.

Pivot table

- [ ] inspect source worksheet headers
- [ ] author `pivot-config.json`
- [ ] preview pivot output
- [ ] upsert with explicit target worksheet and anchor cell
- [ ] read target range to verify

mbs pivot preview --doc-id <DOC_ID> --worksheet-name <SOURCE_SHEET> --spec pivot-config.json --output table
mbs pivot upsert --doc-id <DOC_ID> --target-worksheet-name PivotResult --anchor-cell A1 --spec pivot-config.json
mbs excel-worksheet read --doc-id <DOC_ID> --worksheet-name PivotResult --range A1:H30 --output table

See references/pivot-tables.md.

Trace formula lineage

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

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>

If mbs share visibility returns 403 with an owner-only message, classify it as owner_permission_required / permission_skipped. If workbook metadata already shows the requested public/editor or public/viewer visibility, report it as a share warning rather than a dashboard failure; otherwise ask the owner or service account to update visibility. 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