# DeepCell CLI 完整参考

五个界面、每一个指南主题、每一条命令、每一条规则——全部由 CLI 自身生成，所以本页写的就是你的终端会回答的内容。

Source: https://deepcell.net/product/cli.md

## 从这里开始

先安装 CLI。开始之前不需要账号——第一次调用会自动创建匿名会话，本页所有内容在全新安装上都能直接用。

macOS / Linux
```bash
curl -LsSf https://deepcell.net/install.sh | sh
```

Windows（PowerShell）
```powershell
irm https://deepcell.net/install.ps1 | iex
```

然后用一次调用检查安装情况：版本、服务是否可达、你是谁、当前项目是哪个。

```bash
deepcell doctor
```

先读引导式上手说明，再列出项目里有什么。第二条能打印出结果，就说明已经连通。

```bash
deepcell guide orient/start
deepcell ls
```

登录是可选的，而且应该发生在你的第一个文件之后，而不是之前。登录能让成果不随匿名会话消失、解除匿名额度限制，并让你分享做出来的东西。

```bash
deepcell login
```

## 五个界面

参考内容按你此刻要问的问题划分：每一类知识的形态不同、查阅频率不同、过时的风险也不同。按问题去找对应的那一个，而不是把整套读完。

| 界面 | 你此刻在问什么 | 它回答什么 |
| --- | --- | --- |
| deepcell help | 这条命令到底怎么写？ | Every command, flag, exit code and example as one document. |
| deepcell rules | 什么是任何时候都必须成立的？ | The invariants applicable to a .deepcell work shape. |
| deepcell guide | 这个阶段的标准做法是什么？ | Explain how DeepCell itself works. |
| deepcell ref | 这里合法的取值有哪些？ | Look up legal values, and resolve any typed id — the format's or a document's. |
| deepcell example get | 正确的成品长什么样？ | Write an example document to a local file. |

其中两个——命令调用参考和合法取值参考——直接由实现推导而来，因此不可能与实现不一致。另外三个是人工撰写的，但都以机械方式绑定回实现：它们引用的每一个 id 都必须能解析，解析不到 CI 就会失败。

本页不是第六个界面，而是上述五个的一次呈现，数据来自 CLI 对外提供的同一份清单，因此两者不可能描述出不同的命令。清单版本： 0.7.4

## 全部指南主题

主题是有顺序的操作流程，按所属工作阶段分组。只读你当前阶段的那一篇，不必通读整个索引。任意一篇都可以在终端里打印出来：

```bash
deepcell guide orient/start
```

| 主题 | 阶段 | 涵盖内容 |
| --- | --- | --- |
| orient/start | orient | Inspect the environment and existing work before choosing a route |
| orient/how-to-work | orient | Shared working contract for connected, challengeable DeepCell work |
| orient/surface-ownership | orient | Know which surface owns each fact, judgment, explanation, and takeaway |
| orient/concepts | orient | Understand the six core concepts used by the Spreadsheet surface |
| orient/choose-shape | orient | Choose the decision, evidence, and work surfaces the question needs |
| ingest/tabular | ingest | Bring external tables in faithfully without inventing projections |
| ingest/model-workbook | ingest | Convert a formula-bearing model workbook without flattening its logic |
| ingest/presentation | ingest | Convert a deck or PDF beside a model into a bound Deck that reproduces its pages |
| generate/first-file | generate | Create one valid file for the selected surfaces and build on it |
| generate/structure | generate | Define Spreadsheet items, contexts, statuses, and dimensions |
| generate/calcs | generate | Encode derived Spreadsheet values as dependency-tracked calculations |
| generate/values | generate | Author input values and provenance at their exact coordinates |
| generate/whole-doc | generate | Use one whole-document write when the complete initial shape is known |
| revise/premise-change | revise | Change a premise, recompute calculations, and reassess every connected surface |
| revise/values | revise | Change existing values with the narrowest typed operation |
| revise/structure | revise | Change definitions while preserving references and dependent work |
| revise/scenarios | revise | Compare what-if overlays without copying the underlying work |
| revise/reasoning | revise | Record claims and premises incrementally and preserve their lifecycle |
| revise/questions | revise | Answer follow-ups into the file, and prepare the questions a reviewer will ask |
| revise/history | revise | Review and preserve the versioned history of the work |
| verify/lint | verify | Run describe --lint — structural and reasoning rules — as the first verification move |
| verify/query-back | verify | Read calculated outputs back and catch an empty or misaddressed grid |
| verify/review | verify | Audit every selected surface before calling the work complete |
| present/layout | present | Lay out Spreadsheet results for inspection and delivery |
| present/prose | present | Author long-form explanation with resolvable same-file references |
| present/charts | present | Turn selected Spreadsheet ranges into charts without copying values |
| present/decks | present | A Deck for its reader, every figure and claim bound to the document |
| present/deck-style | present | Decide the deck's CSS for its reader — a pack is a preset, not a shape — and apply it before writing slides |
| present/deliver | present | Share or export finished work within the active transport limits |
| role/model-builder | role | Builds or revises the Spreadsheet surface of one document — structure, drivers, calculations — and proves the grid populated. |
| role/deck-author | role | Authors or restyles the Deck surface over a model that already exists. |
| role/researcher | role | Answers a question that leaves the project — research, diligence, a proposal — and records source-backed findings in the file. |
| role/deliverable-reviewer | role | Judges whether passages still say something true after an upstream change; proposes edits, never writes them. |
| overview | 参考 | Template — three-statement model architecture: sheet layout, item order ranges, and the IS/BS/CF golden loop |
| assumptions | 参考 | Template — assumptions sheet: driver categories, order ranges, and why drivers are Values while anything derived is a CalcDef |
| income-statement | 参考 | Template — income statement items and formulas, revenue through net income |
| balance-sheet | 参考 | Template — balance sheet items and formulas, plus the assets = liabilities + equity check |
| cash-flow | 参考 | Template — cash flow statement: operating/investing/financing sections and the cash reconciliation |
| dcf | 参考 | Template — DCF valuation: free cash flow build, WACC, terminal value, and the equity bridge |
| scenarios | 参考 | Template — worked bull/base/bear setup: which variables to override and by how much (for the mechanics, read revise/scenarios) |
| validation | 参考 | Template — integrity check items every model should carry (balance check, cash reconciliation, coverage ratios) |
| orchestrator | 参考 | How to run DeepCell work — what the job is, when it is done, and how to look things up instead of guessing |
| bank | 参考 | Template — bank / NIM model: rate × balance grid, net interest income, efficiency ratio, provision |
| insurance | 参考 | Template — insurance model: earned premium, loss/expense ratios, combined ratio, underwriting result |
| reit | 参考 | Template — REIT model: NOI, FFO, AFFO, real-estate depreciation add-back |
| build-from-scratch | 参考 | Build playbook — starting with no existing .deepcell file, from empty project to a valid model |
| account-categorization | 参考 | Mapping a company's own statement labels onto a standard chart of accounts, without editing the extraction |
| chart-of-accounts-gaap | 参考 | Template — US GAAP standard chart of accounts (order 4000-4299), item ids matching the statement templates |
| chart-of-accounts-ifrs | 参考 | Template — IFRS standard chart of accounts, and where it diverges from US GAAP |
| chart-of-accounts-cas | 参考 | Template — Chinese Accounting Standards (企业会计准则) chart of accounts for A-share filers |
| non-gaap-metrics | 参考 | Template — non-GAAP adjusted metrics (order 4300-4399): adjusted EBITDA, net income, and EPS |
| schema-matching | 参考 | Mapping external data (xlsx/csv) to .deepcell item and context dimensions |
| house-rules | 参考 | House rules — the non-negotiable invariants every model must satisfy |
| review-dimensions | 参考 | Review dimensions — the model audit checklist (integrity, formulas, coverage, sanity, grounding, reasoning, intent, presentation) |
| model-scopes | 参考 | Choosing model scope — P&L+DCF default, 3-statement triggers, industry models |
| sec-extraction | 参考 | SEC extraction — raw historical layer, model mapping layer, provenance rules |
| cn-extraction | 参考 | A-share (cninfo) extraction — CAS statements from report PDFs, #page deep links, canonical item map |
| excel-import | 参考 | Excel import — dimension mapping, formula conversion, excel_import provenance |

## 全部命令

每一条命令都列出调用形式、它接受的参数与选项以及各自的取值要求、各退出码的含义，以及一条可直接运行的示例。整份目录也可以用一次调用取回为机器可读数据——缓存一次，胜过为每条命令各跑一趟：

```bash
deepcell help
```

### orient — look at what exists before adding to it

#### cat

Print file content (XML) to stdout.

deepcell cat <filename>
```bash
deepcell cat model.deepcell
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Show file at specific revision. |
| --workspace <workspace_slug> | text | — | Override active workspace. |

退出码： 0 — completed

#### cell-meta

Show metadata for a single cell (formula, dependencies, data source).

deepcell cell-meta <filename> [item_ref_pos] [context_ref_pos]
```bash
deepcell cell-meta model.deepcell Revenue FY2026E
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| item_ref_pos | text | 可选 |
| context_ref_pos | text | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --item <item_opt> | text | — | Item ref (alternative to the ITEM_REF positional). |
| --context <context_opt> | text | — | Context ref (alternative to the CONTEXT_REF positional). |
| --status <status_ref> | text | — | Status reference (e.g. 'actual'). A CONSTRAINT, not a hint: the read may answer from that bucket or the untagged one, never from a third. Omit to let the document decide which status answers. |
| --scenario <scenario_ref> | text | — | Scenario dimension (omit for the base cell). |
| --custom-dimensions <custom_dimensions> | text | — | Custom dimensions as 'dim:member;dim:member', e.g. 'geography:na'. |
| --cells <cells_spec> | text | — | Several cells in one call, spelled as `query --cells` spells them (`WACC@FY2026E,EV@FY2026E#projected`, `Item[CTX]` too; `Dep_Years` or `Dep_Years@` for a scalar). Replaces the positional coordinate. |

退出码： 0 — completed

#### describe

Show a document's shape: sheets, the five dimensions, documents, decks.

deepcell describe <filename>
```bash
deepcell describe model.deepcell --lint
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --include-reasoning | boolean | — | Append the reasoning: counts and the reading path. With --full, also each argument claim's body and every cell it cites, read back as `address = value` with the status and world it was read under. |
| --scenario <scenario_id> | text | — | Scenario ID whose value overrides to apply. |
| --lint | boolean | — | Include canonical structural findings; exit 1 on error-level ones. Warn-level findings print and exit 0 — read them. |
| --since <since_revision> | text | — | With --lint: mark each finding pre-existing or new against this revision. Use `HEAD~1` for the commit before yours, or a SHA from `deepcell log`. |
| --sheet <sheet_id> | text | — | One sheet in full: its blocks, and every item it renders with label, type and units. Plain output only. |
| --full | boolean | — | Everything listed at once — every item, block, heading, slide and source — instead of the frame. Plain output only. |
| --measure | boolean | — | With --lint: measure every deck slide that has no fit measurement yet (one browser pass per slide in the export service) before reporting. Slides are measured on the write that changes them; use this for a deck that arrived by sync or import, or was restyled. |
| --fail-on <fail_on> | any \| introduced | any | With --lint --since: which error-level findings set the exit code. `any` is the whole model, as always. `introduced` exits 1 only on findings the baseline did not have — a scoped edit stops failing on a slide it never touched. A finding whose provenance is unknown (a slide unmeasured at the baseline) prints but does not gate. |
| --workspace <workspace_slug> | text | — | Override active workspace. |

退出码： 0 — completed · 1 — read-only-check

#### grep

Search the XML of .deepcell files for a regular expression.

deepcell grep <pattern> [files...]
```bash
deepcell grep Revenue
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| pattern | text | 必填 |
| files... | text | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --file <file_opts> | text | — | Search within a specific file (repeatable; same as a FILE argument). |
| --ignore-case | boolean | — | Case-insensitive search. |

退出码： 0 — completed

#### ls

List files in the active workspace.

```bash
deepcell ls
```

退出码： 0 — completed

#### query

Query a .deepcell file.

deepcell query <filename> [item_ref] [context_ref] [status_ref]
```bash
deepcell query model.deepcell Revenue FY2026E
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| item_ref | text | 可选 |
| context_ref | text | 可选 |
| status_ref | text | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --status <status_opt> | text | — | Status dimension — the same thing as the third positional. `edit`, `defs add-calc` and `cell-meta` all spell it this way; accepted here so the four agree. |
| --scenario <scenario_ref> | text | — | Scenario dimension (omit for default scenario). |
| --custom-dimensions <custom_dimensions> | text | — | Custom dimensions as 'dim:member;dim:member', e.g. 'geography:na'. |
| --cells <cells_arg> | text | — | Read several cells that do NOT share a row, in one call: 'ITEM@CONTEXT,ITEM@CONTEXT,...' (add a third '@STATUS' segment per cell to pin its status; the link spelling ITEM[CONTEXT]#STATUS, or ITEM@CONTEXT#STATUS, names the same cell). A bare ITEM reads by the item's shape: a scalar's one cell, or every period of a period item. This is the check-my-outputs form — a comma-separated CONTEXT_REF only walks one item. |
| --sheet <sheet_id> | text | — | Render a full sheet as markdown table. |
| --block <block_id> | text | — | Render a specific block within a sheet. |
| --chart-details | boolean | — | Return structured chart values, annotation bindings and diagnostics (requires --sheet). |
| --chart-width <chart_width> | integer range | — | Validate shared chart layout at this CSS-pixel width; requires --chart-height, --chart-details and --block. |
| --chart-height <chart_height> | integer range | — | Target CSS-pixel height for --chart-width layout validation. |
| --offset <offset> | integer range | — | An item read's page: the first cell to show (0-based). A page that leaves cells out ends with the command for the next one. |
| --limit <limit> | integer range | — | An item read's page size (default 20). |
| --workspace <workspace_slug> | text | — | Override active workspace. |

退出码： 0 — completed

### ingest — external data in (skip for from-scratch work)

#### import

Import an xlsx or csv file into a .deepcell document.

deepcell import <file> --items <items> --contexts <contexts>
```bash
deepcell import variance.xlsx --name variance_import --items '[{"id":"Revenue","name":"Revenue","level":0,"row":2,"sheet":"Variance"}]' --contexts '[{"id":"FY25A","name":"FY25 actual","period_type":"annual","status":"actual","column":"B"}]'
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| file | path | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --items <items> | text | 必填 | Items JSON string or path to JSON file. |
| --contexts <contexts> | text | 必填 | Contexts JSON string or path to JSON file. |
| --name <name> | text | — | Name for the .deepcell file (default: the input file's stem). A file of that name is replaced. |
| --workspace <workspace> | text | — | Target workspace slug. |
| --aggregations <aggregations> | text | — | Aggregation rules JSON string or path to JSON file. |
| --keep-raw | boolean | — | Store raw values alongside aggregated results. |

退出码： 0 — completed · 1 — partial

#### ingest cn extract

Extract one statement's table — rows, canonical items, and the <Source> to record.

deepcell ingest cn extract <pdf_url>
```bash
deepcell ingest cn extract https://static.cninfo.com.cn/finalpage/2026-03-28/1224567890.PDF --statement income --persist
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| pdf_url | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --statement <statement> | text | 合并利润表 | Chinese heading or income \| balance \| cash_flow |
| --persist | boolean | — | Store the source PDF once in DeepCell storage and list it in the active project, so a viewer there opens it even after the cninfo link moves. The file name comes back as `mirror_file`, for the <Source> <Mirror>. --no-persist skips it (faster); the <Locator> is the cninfo original either way. |

退出码： 0 — completed

#### ingest cn filings

List annual / interim reports with PDF permalinks.

deepcell ingest cn filings <code>
```bash
deepcell ingest cn filings 600519 --type annual --count 5
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| code | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --type <filing_type> | text | annual | annual \| interim \| semiannual \| q1 \| q3 |
| --count <count> | integer range | 5 | number of reports (1-30) |

退出码： 0 — completed

#### ingest cn search

Resolve a 6-digit code, company name (中文简称), or pinyin.

deepcell ingest cn search <keywords>
```bash
deepcell ingest cn search 600519
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| keywords | text | 必填 |

退出码： 0 — completed

#### ingest cn statements

Locate the financial statements inside a report PDF (page + scale).

deepcell ingest cn statements <pdf_url>
```bash
deepcell ingest cn statements https://static.cninfo.com.cn/finalpage/2026-03-28/1224567890.PDF
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| pdf_url | text | 必填 |

退出码： 0 — completed

#### ingest sec filings

List recent filings: accession, period end, primary-document URL.

deepcell ingest sec filings <ticker>
```bash
deepcell ingest sec filings AMD --type quarterly --count 4
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| ticker | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --type <filing_type> | annual \| quarterly | annual | annual (10-K / 20-F) or quarterly (10-Q) |
| --count <count> | integer range | 5 | number of filings (1-20) |

退出码： 0 — completed

#### ingest sec pull

Statements for N years as an ops file and a values file, sources attached.

```bash
deepcell ingest sec pull <ticker>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| ticker | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --years <years> | integer range | 3 | Closed fiscal years of statements to pull. |
| --quarter | boolean | — | Also the latest 10-Q filed after the last 10-K (default on). |
| --filename <filename> | text | — | The .deepcell the result is for: ids it already declares are reused instead of re-added. |
| --model-layer | boolean | — | Also write the standard model layer (Revenue_Model … CFO_Model, subtotals, check rows, a Financial Model sheet) mapped by XBRL concept, as a third ops payload applied after the values. |
| --out-dir <out_dir> | directory | — | Where the payload files go (default: the current directory). |
| --inline | boolean | — | Write no files: return the ops and the value batches in the output, for `defs apply --ops` and `edit --batch` (the MCP server always uses this, since its disk is not yours). |

退出码： 0 — completed

#### ingest sec report

One report as rows: label as filed, XBRL concept, values.

deepcell ingest sec report <ticker> <accession> <file>
```bash
deepcell ingest sec report AMD 0000002488-26-000018 R4.htm
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| ticker | text | 必填 |
| accession | text | 必填 |
| file | text | 必填 |

退出码： 0 — completed

#### ingest sec reports

List a filing's XBRL reports — statements, notes and their detail tables.

deepcell ingest sec reports <ticker> <accession>
```bash
deepcell ingest sec reports AMD 0000002488-26-000018 --grep segment
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| ticker | text | 必填 |
| accession | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --grep <pattern> | text | — | Only reports whose name contains this text (e.g. segment). |

退出码： 0 — completed

#### ingest sec search

Resolve a company name, ticker or CIK to its EDGAR ticker and CIK.

deepcell ingest sec search <keywords>
```bash
deepcell ingest sec search AMD
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| keywords | text | 必填 |

退出码： 0 — completed

#### ingest symbol-font

Convert one font glyph into self-contained checkbox geometry.

deepcell ingest symbol-font --font <font> --state <state>
```bash
deepcell ingest symbol-font --font symbols.ttf --character ★ --state 42
```

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --attribution <attribution> | text | — | Source or license note preserved with the converted symbol. |
| --font <font> | text | 必填 | Local TTF/OTF/TTC file, - for binary stdin, or base64:DATA. |
| --state <state> | integer range | 必填 | Spreadsheet integer selecting this symbol. |
| --character <character> | text | — | One Unicode character; select this or --glyph-name. |
| --glyph-name <glyph_name> | text | — | Exact font glyph name; select this or --character. |
| --font-index <font_index> | integer range | 0 | Collection member; zero for a standalone font. |
| --format-ref <format_ref> | text | — | Existing Format for symbol paint; otherwise inherit the checkbox Format. |
| --variations <variations> | text | {} | JSON map of font variation axis tags to design-space values. |

退出码： 0 — completed

#### ingest symbol-icon

Convert a named icon into self-contained checkbox geometry.

deepcell ingest symbol-icon --name <name> --state <state>
```bash
deepcell ingest symbol-icon --name trending-up --state 42
```

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --attribution <attribution> | text | — | Source or license note preserved with the converted symbol. |
| --name <name> | text | 必填 | Exact name from deepcell ref icon. |
| --state <state> | integer range | 必填 | Spreadsheet integer selecting this symbol. |
| --format-ref <format_ref> | text | — | Existing Format for symbol paint; otherwise inherit the checkbox Format. |

退出码： 0 — completed

#### ingest symbol-svg

Convert SVG into a self-contained checkbox symbol and Format operations.

deepcell ingest symbol-svg --svg <svg> --state <state> --format-prefix <format_prefix>
```bash
deepcell ingest symbol-svg --svg symbol.svg --state 42 --format-prefix imported
```

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --attribution <attribution> | text | — | Source or license note preserved with the converted symbol. |
| --svg <svg> | text | 必填 | Inline SVG, a local UTF-8 SVG file path, or - for stdin. |
| --state <state> | integer range | 必填 | Spreadsheet integer selecting this symbol. |
| --format-prefix <format_prefix> | text | 必填 | Unused Format identifier prefix for imported paints. |

退出码： 0 — completed

#### verify-import

Check every cited cell of FILENAME against WORKBOOK, and how much of WORKBOOK the document carries.

deepcell verify-import <filename> <workbook>
```bash
deepcell verify-import variance_import.deepcell variance.xlsx --min-coverage 0.9
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| workbook | path | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --workspace <workspace> | text | — | Workspace slug the document lives in. |
| --rel-tol <rel_tol> | float | 0.000001 | Relative tolerance a cell may differ by and still match. |
| --min-coverage <min_coverage> | float | 0.5 | Floor each sheet's inputs-cited ratio and the formulas-carried ratio are held to. |

退出码： 0 — completed · 1 — read-only-check

### generate — create one file, then build only the surfaces the work needs

#### deck add

Add a Deck to a .deepcell file.

deepcell deck add <filename> --name <name>
```bash
deepcell deck add model.deepcell --name <name>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --deck-id <deck_id> | text | — | Deck id. Omit to have one assigned. |
| --name <name> | text | 必填 | Display name for the deck. |
| --aspect-ratio <aspect_ratio> | aspect_ratio | — | Slide aspect ratio as W:H, between 1:3 and 3:1 — 16:9, 4:3, 9:16, 1:1. Omit for the format default (16:9), the recommended shape. Fixed at creation: slides do not reflow to another ratio. |
| --style <style_pack> | text | — | Open the deck on a style pack — institutional, consulting, editorial, product (`deepcell ref deck-style`). Its CSS becomes the deck's <Style>. |
| --index <index> | integer | — | Position among decks (0-based). |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed

#### deck add-slide

Add an empty slide to a deck.

deepcell deck add-slide <filename> --deck <deck_id> --name <name>
```bash
deepcell deck add-slide model.deepcell --deck <deck_id> --name <name>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --deck <deck_id> | text | 必填 | Deck to add the slide to. |
| --slide-id <slide_id> | text | — | Slide id. Omit to have one assigned. |
| --name <name> | text | 必填 | Display name for the slide. |
| --index <index> | integer | — | Position within the deck (0-based). |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed

#### deck bind

Point a slide at a live value, or update an existing binding.

deepcell deck bind <filename> --deck <deck_id> --binding-id <binding_id> --binding-kind <binding_kind>
```bash
deepcell deck bind model.deepcell --deck <deck_id> --binding-id <binding_id> --binding-kind <binding_kind>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --deck <deck_id> | text | 必填 | Deck the binding lives on. |
| --binding-id <binding_id> | text | 必填 | Binding id. Reusing one updates it in place. |
| --binding-kind <binding_kind> | value \| series \| chart \| table \| reasoning \| source \| htmlblock \| derived \| label | 必填 | What the binding renders. Decides which address flag it takes. |
| --field <field> | text | — | Which text of the addressed thing to render, not an address itself. |
| --op <op> | sum \| avg \| min \| max \| delta \| pct_change \| share \| cagr | — | What a `derived` binding computes over its --refs, in order: sum, avg, min, max over all of them; delta (second minus first); pct_change ((second - first) / first); share (first / second); cagr over the run. |
| --ref <ref> | text | — | Single coordinate the binding reads. |
| --refs <refs> | text | — | Comma-separated coordinates — the address a `series` or `derived` binding takes. Single-quote an item id that contains a comma. |
| --number-format <number_format> | text | — | Excel-style number pattern the value renders with, all three sections — `#,##0.0;(#,##0.0);"-"`, `0.0%;(0.0%);"-"` (`deepcell ref format/pattern`). It labels the stored value and never divides it. |
| --prefix <prefix> | text | — | Text rendered before the value. |
| --suffix <suffix> | text | — | Text rendered after the value. |
| --rows <rows> | text | — | Which item rows a `table` shows, the way a block's itemOrders picks them: item ids, @order values and low-high order ranges, comma-separated (`Revenue,EBITDA`, `1040-1070`). Omitted, every row. |
| --columns <columns> | text | — | Which value columns a `table` shows, by whatever the block's column axis holds: context ids with A..B ranges (`FY2027..FY2029`), or scenario / status ids when the block lays those out as columns. Omitted, every column. |
| --transpose | boolean | — | Turn a `table`: each period or scenario becomes a row, the item labels the header. |
| --max-rows <max_rows> | integer range | — | Rows a `table` shows before the plan says how many it left out (default 40). |
| --caption <caption> | text | — | Plain text drawn as a `table`'s <caption>. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed

#### deck brand

Recolour a deck, or change its faces, by ROLE without touching its stylesheet.

deepcell deck brand <filename> --deck <deck_id>
```bash
deepcell deck brand model.deepcell --deck <deck_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --deck <deck_id> | text | 必填 | Deck to recolour. |
| --set <assignments> | text | — | Role override, repeatable: --set accent=#0A5C3B --set font-display=Cambria. Colour roles are the pack's colour names — accent, ink, series-1 … (`deepcell ref deck-style/hooks`); font-display (titles, figures) and font-text take a safe face (`deepcell ref deck-style/fonts`); font-cjk (East Asian text) one of Microsoft YaHei, SimSun, SimHei, DengXian, Microsoft JhengHei. |
| --clear | boolean | — | Remove the brand; the pack's own palette shows again. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed

#### deck delete

Delete a deck and every slide on it.

deepcell deck delete <filename> <deck_id>
```bash
deepcell deck delete model.deepcell <deck_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| deck_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed

#### deck delete-slide

Delete one slide, and the HTML on it.

deepcell deck delete-slide <filename> <slide_id> --deck <deck_id>
```bash
deepcell deck delete-slide model.deepcell <slide_id> --deck <deck_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| slide_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --deck <deck_id> | text | 必填 | Deck the slide belongs to. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed

#### deck footer

Set the deck's folio template, so no slide types its own page number.

deepcell deck footer <filename> --deck <deck_id>
```bash
deepcell deck footer model.deepcell --deck <deck_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --deck <deck_id> | text | 必填 | Deck whose folio to set. |
| --set <template> | text | — | The folio, one line: literal text plus {n} (slide position), {count}, {name} (slide name), {deck}, {text:BINDING} / {value:BINDING} (a binding's display string), and one `\|` splitting left from right. |
| --clear | boolean | — | Remove the template; slides keep only footers of their own. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed

#### deck rename

Change a deck's display NAME.

deepcell deck rename <filename> <deck_id> <new_name>
```bash
deepcell deck rename model.deepcell <deck_id> <new_name>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| deck_id | text | 必填 |
| new_name | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed

#### deck rename-slide

Change a slide's display NAME.

deepcell deck rename-slide <filename> <slide_id> <new_name> --deck <deck_id>
```bash
deepcell deck rename-slide model.deepcell <slide_id> <new_name> --deck <deck_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| slide_id | text | 必填 |
| new_name | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --deck <deck_id> | text | 必填 | Deck the slide belongs to. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed

#### deck reorder

Move a deck to TO_INDEX in the deck order (0-based).

deepcell deck reorder <filename> <deck_id> <to_index>
```bash
deepcell deck reorder model.deepcell <deck_id> <to_index>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| deck_id | text | 必填 |
| to_index | integer | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed

#### deck reorder-slide

Move a slide to TO_INDEX within its deck (0-based).

deepcell deck reorder-slide <filename> <slide_id> <to_index> --deck <deck_id>
```bash
deepcell deck reorder-slide model.deepcell <slide_id> <to_index> --deck <deck_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| slide_id | text | 必填 |
| to_index | integer | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --deck <deck_id> | text | 必填 | Deck the slide belongs to. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed

#### deck style

Set a deck's stylesheet: a PACK by name, or a CSS file, whole.

deepcell deck style <filename> --deck <deck_id>
```bash
deepcell deck style model.deepcell --deck <deck_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --deck <deck_id> | text | 必填 | Deck to restyle. |
| --pack <pack> | text | — | A style pack — institutional, consulting, editorial, product (`deepcell ref deck-style`). The server writes its CSS. |
| --css-file <css_file> | file | — | The deck's own stylesheet, whole (use '-' for stdin). Replaces, never merges. |
| --keep-own-rules | boolean | — | With --pack: keep the rules written after the old pack (the deck's own) and replace only the pack. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed

#### deck unbind

Remove one or more bindings, leaving whatever the slide's HTML says in their place.

deepcell deck unbind <filename> [binding_ids...] --deck <deck_id>
```bash
deepcell deck unbind model.deepcell --deck <deck_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| binding_ids... | text | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --binding-id <binding_id_flags> | text | — | A binding to remove — the same as naming it positionally. Repeatable. |
| --deck <deck_id> | text | 必填 | Deck the bindings live on. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed

#### defs add-axis-member

Add a row or a column to a Block.

deepcell defs add-axis-member <filename> --sheet <sheet_id> --block <block_id> --axis <axis> --member <member> --ref <ref>
```bash
deepcell defs add-axis-member model.deepcell --sheet variance --block revenue_table --axis rows --member item --ref Gross_Profit
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --sheet <sheet_id> | text | 必填 | Sheet containing the block. |
| --block <block_id> | text | 必填 | blockId to edit. |
| --axis <axis> | rows \| columns | 必填 | Which axis to edit: 'rows' (the block's @itemOrders) or 'columns' (its @contextRefs). |
| --member <member> | item \| context | 必填 | What kind of id --ref is. Pair 'item' with rows, 'context' with columns. |
| --ref <ref> | text | 必填 | The item id or context id to add. On --axis columns, a range 'A..B' adds every context from A to B inclusive, in context order (e.g. 'D2017_05_18..D2021_05_18' for a daily series); delete-axis-member removes it whole. |
| --index <index> | integer range | — | 0-based position on the axis (default: append at the end). |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs add-block

Add a presentation Block (table or chart) to a sheet.

deepcell defs add-block <filename> --sheet <sheet_id> --block-type <block_type> --name <name>
```bash
deepcell defs add-block model.deepcell --sheet variance --block-type table --name 'Revenue vs budget' --item-orders Revenue,COGS --context-refs FY2025,FY2026
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --sheet <sheet_id> | text | 必填 | Sheet to add the block to. |
| --block-type <block_type> | text | 必填 | One of the types `deepcell ref block-type` lists — table, key_value, chart, sensitivity, text. Any other value is refused: the renderer would skip the block, so it would be written and never drawn. |
| --name <name> | text | 必填 | Display name / section heading. |
| --item-orders <item_orders> | text | — | Rows, in order — item ids, @order values, or lo-hi order ranges, comma separated (e.g. 'revenue,cogs,gross_profit' or '4000-4099'; 'lo:hi' is the same range as a formula writes it). Stored verbatim as @itemOrders; a number or a range matches @order, anything else must be a defined itemId. Every list of items reads this grammar. Omit and the block renders empty — see the note above. |
| --context-refs <context_refs> | text | — | Comma-separated context ids forming the block's columns, in order (e.g. 'FY2024,FY2025'); 'A..B' is a range, every context from A to B inclusive in context order (e.g. 'FY2024,D2017_05_18..D2021_05_18'). Omit to show every context. |
| --index <index> | integer | — | Insertion index within the sheet (default: append at the end). |
| --format-ref <format_ref> | text | — | FormatDefinitions id this block resolves against. Omit and the block takes the document default (the Format named default_format, else the first one defined). See `deepcell ref format`. |
| --chart-type <chart_type> | text | — | — |
| --category-axis <category_axis> | text | — | — |
| --chart-spec <chart_spec> | text | — | The chart, as a JSON object (chart blocks; a chart block written without one draws its selection as grouped columns). Compact: {"family":"line","series":[{"itemRef":"Revenue"}]} over the block's contexts, with categoryAxis, arrangement, totalItemRefs and the Block's ref attributes; {} charts the block's selection. Families: column (vertical), bar (horizontal), line, area, waterfall, range_bar, scatter, pie, doughnut, funnel, radar. Explicit: with "data". Inspect with `deepcell query --chart-details`. |
| --clear-chart-spec | boolean | — | — |
| --chart-annotations <chart_annotations> | text | — | — |
| --total-item-refs <total_item_refs> | text | — | — |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs add-calc

Add a CalculationDefinition (formula).

deepcell defs add-calc <filename> --item <item_id> --formula <formula>
```bash
deepcell defs add-calc model.deepcell --item Revenue --calc-id calc_revenue --formula 'Units_Sold[CURRENT] * Unit_Price[CURRENT]' --status projected
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --item <item_id> | text | 必填 | Item the calc resolves into (itemId). |
| --calc-id <calc_id> | text | — | Stable calcId for the new calc (e.g. 'calc_stress_low'). Errors if the id is already taken, unless --replace. Omit to have one assigned — but an auto id is what `defs delete-calc` and `reasoning add-claim --calc-ref` must then quote, so choose your own when the calc has to be citable. |
| --formula <formula> | text | 必填 | Jingwei formula, e.g. "Revenue[PREVIOUS] * 1.1". |
| --context <context_ref> | text | — | Pin calc to one or more contextRefs. Pass a CSV (e.g. 'FY25,FY26,FY27') or a range ('FY25..FY27', every period from the first to the last in context order) to pin a roll-forward chain to several periods in one call — omit the seed period so its literal is kept. Omit entirely to fan out across every period: a literal there is overwritten, except that a formula reading its own item skips the periods holding one (its seeds). |
| --scenario <scenario_ref> | text | — | Limit calc to this scenarioRef. |
| --status <status_ref> | text | — | Pin calc to a statusRef (e.g. 'projected'). Strongly recommended for forecast formulas so they coexist with the historical actuals in the same item/context slots — without it the projection stores one untagged cell that answers every status, leaving the actuals nowhere to sit. Not enforced: omitting it succeeds, and the cost shows up later as an actual you cannot store. |
| --replace | boolean | — | With --calc-id naming a calc that exists: overwrite it in place (same id, same position) instead of refusing the duplicate id. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs add-context

Add a ContextDefinition — a period, or a non-temporal axis member.

deepcell defs add-context <filename>
```bash
deepcell defs add-context model.deepcell --name FY2025 --context FY2025 --kind period --state closed --status actual
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --name <name> | text | — | The context IDENTIFIER (@contextId), e.g. 'Low_Rent' — not a display label. Must satisfy the reference-id grammar. Set the readable name afterwards with `defs update-context --label`. |
| --status <status_ref> | text | — | statusRef (optional). |
| --context <context_ref> | text | — | The context IDENTIFIER (@contextId) under the op's wire name — the same thing as --name. If both are given, --context wins; with neither, an opaque `<kind>_N` id (e.g. `period_6`) is assigned. |
| --kind <kind> | text | — | Context kind. Omit (or 'period' / temporal alias) for time columns; pass 'program', 'segment', 'fund', 'region', 'entity', 'product', 'other' (or any snake_case label, ≤32 chars) for non-temporal axes. Always written as @kind on the <Context> element. |
| --state <state> | text | — | Period state: closed \| open \| future. This is what says whether the period is over — never the A/E suffix on a context id. Only meaningful for --kind period. |
| --as-of <as_of> | text | — | ISO YYYY-MM-DD the period's numbers are stated as of. Documentation and lint input only; never consulted when rendering. |
| --granularity <granularity> | text | — | Period length: annual \| semiannual \| quarterly \| monthly (written as <Type>). Growth, margin and CAGR checks compare only periods of one granularity. |
| --start-date <start_date> | text | — | First day of the period (<StartDate>). |
| --end-date <end_date> | text | — | Last day of the period (<EndDate>). |
| --parent <parent_context> | text | — | The enclosing period's id, e.g. FY2026 for Q1_2026 (@parentContext); SUM_CHILDREN sums over it. |
| --index <index> | integer | — | Position in contexts list (omit to append at end). |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs add-dimension

Declare a custom Dimension (a third axis such as geography or product line), optionally with its members.

deepcell defs add-dimension <filename> <dimension_id>
```bash
deepcell defs add-dimension model.deepcell <dimension_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| dimension_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --label <label> | text | — | Display label for the dimension. |
| --member <members> | text | — | Declare a member with it; repeat in expansion order (--member na=North America --member eu). |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs add-doc

Add a <Document> — the prose that ships with the model.

deepcell defs add-doc <filename>
```bash
deepcell defs add-doc model.deepcell --doc-id variance_note --name 'July variance note' --lang en --body-file variance-note.md
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --doc-id <doc_id> | text | — | Document identifier (@docId). Must match [A-Za-z0-9_.-]+ so a deepcell:doc/<id> reference to it parses back. |
| --name <name> | text | — | Display title. |
| --lang <lang> | text | — | BCP-47 language tag, e.g. 'en' or 'zh'. |
| --body-file <body_file> | file | — | File holding the initial body (else empty); `-` reads stdin. |
| --notation <notation> | markdown \| text | — | What the body IS. A new document is markdown unless you say 'text', which also stops anchors being stamped into it. |
| --index <index> | integer | — | Position among documents. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs add-format

Add a <Format formatId="..."> to FormatDefinitions.

deepcell defs add-format <filename> <format_id>
```bash
deepcell defs add-format model.deepcell fmt_statement --rule 'default:fontName=Arial'
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| format_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --rule <rule_strs> | text | — | One rule as semicolon-separated key=value pairs, e.g. 'target=item:Average_Headcount; number_format=#,##0.0;(#,##0.0);"-"' (one decimal on one row; keep the negative and zero sections every default carries). A numberFormat on target=default is a catch-all and yields to the item's family default, so it changes no digits — use an item:, level: or condition: target (`deepcell ref format/pattern`). Commas inside a value (such as Excel number formats) are preserved, and so are the semicolons of a section format ('number_format=#,##0.00;[Red](#,##0.00);0.00'): a fragment that does not open with `key=` belongs to the value before it, an empty one included (as in Excel, an empty section displays nothing: '#,##0.00;;"-"' shows negatives blank and zero as -). Only a trailing ';' is dropped; a format that must end on an empty section goes through --rule-json. A rule may also be one JSON object with the same keys, e.g. '{"target":"item:Revenue","number_format":"+0;-0;0"}'. Repeat the flag for multiple rules. Keys: target, font_color, background_color, stroke_color, font_weight, font_style, font_name, font_size, text_align, indent, number_format, border_top/bottom/left/right. |
| --rule-json <rule_json> | text | — | The rules as a JSON list of objects, for a value the key=value syntax cannot carry: '[{"target":"item:Revenue","number_format":"…"}]'. Mutually exclusive with --rule. |
| --inherit | boolean | — | --no-inherit opts the Format out of the IB default base (a total custom theme; writes @inherit="false"). Default inherits the base (add-on model). See `deepcell ref format`. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs add-item

Add an ItemDefinition (no value).

deepcell defs add-item <filename> --name <name>
```bash
deepcell defs add-item model.deepcell --name Revenue --label Revenue --data-type monetary --scale 6 --currency USD --order-mode append
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --name <name> | text | 必填 | The new itemId, stored as given (trimmed). Use the snake_case long form (Net_Working_Capital) — formulas, blocks and citations quote it; put an abbreviation in --label. |
| --label <label> | text | — | Display label (e.g. 'Gross Margin %'); defaults to a humanized form of --name. Written as one <Label lang="en">: no typed op adds a second locale, so a bilingual item (en + zh) is seeded in the initial `deepcell write`. |
| --level <level> | integer | — | Indent depth (>= 0). Omit it to take the depth under --parent (0 for a root); a level that disagrees with the parent chain is stored as given. |
| --parent <parent_item_id> | text | — | Parent itemId (omit for root). |
| --index <index> | integer | — | Position among siblings (omit to append after the last). Without --order / --order-mode the item takes a free @order beside its neighbours; when none is free every later item shifts +1, and rows a block addresses by order range move with them. |
| --order <order> | integer | — | Explicit @order (must be unique; presentation blocks address rows by order ranges). Overrides --index placement. |
| --order-mode <order_mode> | append | — | 'append' assigns max(existing orders) + 10 — no need to know which orders are taken. Mutually exclusive with --order; overrides --index. |
| --data-type <data_type> | text | — | DataType element (e.g. 'monetary', 'percentage', 'number'). |
| --unit <unit> | text | — | Unit element (e.g. '%', 'hours', 'tonnes'). |
| --scale <scale> | integer | — | Scale element (units multiplier exponent, 6 = millions). A monetary declaration: it sets a monetary item's display digits and is required with --currency (R7). On any other type it changes no digits — set those with an item: numberFormat rule (`deepcell ref format/pattern`). Item @precision and Header DecimalPlaces round what is STORED, never what is displayed. |
| --currency <currency> | text | — | Currency element: an ISO 4217 code ('USD', 'CNY'), or 'XXX' when the source states none (renders no symbol). |
| --shape <shape> | scalar \| period | — | Declare the item's one shape: 'scalar' (one cell, Item[] — a rate, a life, a count) or 'period' (a value per period). Optional: omitted, the item's FIRST write decides (a value with no period makes it a scalar; a calc over scalars and fixed cells is inferred scalar and stamped) — declare it to force a shape. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs add-member

Declare one Member of an existing custom Dimension, so values and calcs may carry `dimension:member`.

deepcell defs add-member <filename> <dimension_id> <member_id>
```bash
deepcell defs add-member model.deepcell <dimension_id> <member_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| dimension_id | text | 必填 |
| member_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --label <label> | text | — | Display label for the member. |
| --index <index> | integer range | — | 0-based position among the dimension's members (default: append). |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs add-period

Add a ContextDefinition (period, or non-temporal axis member).

deepcell defs add-period <filename>
```bash
deepcell defs add-period model.deepcell --name FY2026 --context FY2026 --state future --status projected
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --name <name> | text | — | The period IDENTIFIER (@contextId), e.g. FY2027E — not a display label. Must satisfy the reference-id grammar. Set the readable name afterwards with `defs update-context --label`. |
| --status <status_ref> | text | — | statusRef (e.g. 'projected'). |
| --context <context_ref> | text | — | The context IDENTIFIER (@contextId) under the op's wire name — the same thing as --name. If both are given, --context wins; with neither, an opaque `<kind>_N` id (e.g. `period_6`) is assigned. |
| --kind <kind> | text | — | Context kind. Omit (or pass 'period' / a temporal alias like 'time' / 'year' / 'annual' / 'fy') for time columns; pass e.g. 'program', 'segment', 'fund', 'region', 'entity', 'product', 'other' (or any snake_case label, ≤32 chars) for non-temporal axes. Always written as @kind on the <Context> element. |
| --state <state> | text | — | Period state: closed \| open \| future. This is what says whether the period is over — never the A/E suffix on a context id. Only meaningful for --kind period. |
| --as-of <as_of> | text | — | ISO YYYY-MM-DD the period's numbers are stated as of. Documentation and lint input only; never consulted when rendering. |
| --index <index> | integer | — | Position in contexts list (omit to append at end). |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs add-rule

Add a <Rule> to an existing <Format>.

deepcell defs add-rule <filename> <format_id> --target <target>
```bash
deepcell defs add-rule model.deepcell fmt_statement --target 'level:0:item' --font-weight bold --number-format '#,##0'
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| format_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --target <target> | text | 必填 | Rule @target selector (see `deepcell ref format`). Several rows or columns are one rule: 'item:A,B,C' (alias items:), 'context:FY24..FY26', 'level:0,1'. |
| --bg-color <background_color> | text | — | Hex color '#RRGGBB' for backgroundColor. |
| --stroke-color <stroke_color> | text | — | Chart outline hex color for strokeColor. |
| --font-color <font_color> | text | — | Hex color '#RRGGBB' for fontColor. |
| --font-weight <font_weight> | text | — | 'bold' \| 'normal'. |
| --font-style <font_style> | text | — | 'italic' \| 'normal'. |
| --font-name <font_name> | text | — | Font family name. |
| --font-size <font_size> | float | — | Font size in points. |
| --text-align <text_align> | text | — | 'left' \| 'center' \| 'right'. |
| --indent <indent> | integer | — | Indent character count. |
| --number-format <number_format> | text | — | Excel-style pattern, all three sections, e.g. '#,##0.0;(#,##0.0);"-"' (`deepcell ref format/pattern`). Set on a default or header target it yields to the item's family default. |
| --border-top <border_top> | text | — | e.g. 'thin #000000' (style + optional hex color). |
| --border-bottom <border_bottom> | text | — | Bottom border, e.g. 'thin #000000' (style + optional hex color). |
| --border-left <border_left> | text | — | Left border, e.g. 'thin #000000' (style + optional hex color). |
| --border-right <border_right> | text | — | Right border, e.g. 'thin #000000' (style + optional hex color). |
| --index <index> | integer | — | Insert position (omit to append). |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs add-scenario

Add a ScenarioDefinition.

deepcell defs add-scenario <filename>
```bash
deepcell defs add-scenario model.deepcell --name downside
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --name <name> | text | — | The scenario IDENTIFIER (@scenarioId), e.g. 'Bull' — not a display label. Must satisfy the reference-id grammar. Set the readable name afterwards with `defs update-scenario --label`. |
| --base <base_scenario_ref> | text | — | (unsupported) a scenario has no @baseScenarioRef — see `deepcell guide revise/scenarios`. |
| --context <context_ref> | text | — | The scenario IDENTIFIER (@scenarioId) under the op's wire name, contextRef — the same thing as --name, not a period. Legacy spelling; if both are given, --context wins. |
| --is-default | boolean | — | Mark as the document's default scenario — clears @isDefault from every other scenario. |
| --index <index> | integer | — | Position (omit to append at end). |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs add-sensitivity

Add a sensitivity block (data table / scenario comparison).

deepcell defs add-sensitivity <filename> --sheet <sheet_id> --name <name> --spec-file <spec_file>
```bash
deepcell defs add-sensitivity model.deepcell --sheet summary --name 'IRR sensitivity' --spec-file sensitivity.json
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --sheet <sheet_id> | text | 必填 | Sheet to add the block to. |
| --name <name> | text | 必填 | Display name of the sensitivity block. |
| --index <index> | integer | — | Position among sheet blocks (omit to append at end). |
| --format-ref <format_ref> | text | — | FormatDefinitions id. |
| --spec-file <spec_file> | file | 必填 | JSON with {"axes": [...], "outputs": [...]} (use "-" for stdin). |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs add-sheet

Add a presentation Sheet — a tab in the rendered document.

deepcell defs add-sheet <filename> --label <label>
```bash
deepcell defs add-sheet model.deepcell --label 'Variance review' --index 1
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --label <label> | text | 必填 | Sheet tab label, e.g. 'Dashboard'. |
| --index <index> | integer range | — | 0-based position among the sheets (default: append at the end). |
| --sheet-id <sheet_id> | text | — | The new sheet's id (letters, digits, '_' or '-'), so later commands can address it without reading it back. Errors if taken. Omit to derive one from --label. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs add-source

Declare a <Source> - the one place an outward address may live.

deepcell defs add-source <filename> --id <source_id>
```bash
deepcell defs add-source model.deepcell --id <source_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --id <source_id> | text | 必填 | Stable sourceId, e.g. 'src_aapl_10k_fy25'. |
| --kind <kind> | text | — | What the source physically IS - closed set: filing, webpage, pdf, workbook, dataset, query, transcript, media, message, user_input, document, person, derived, other. user_input is the request itself - a figure the person typed. What it is USED AS goes in --role. |
| --role <role> | text | — | What the source is being used AS - free text: historical_actual, assumption, analyst_estimate, management_guidance, industry_benchmark, market_data, manual, ... |
| --reach <reach> | text | — | Can a recipient open it? public \| account \| private \| offline. 'private' withholds the locator on share and export; 'offline' means no locator exists, which is a complete record, not a broken one. |
| --title <title> | text | — | Human-readable title - what renders when the locator is withheld. |
| --locator <locator> | text | — | The one outward address (URL, path, DSN). |
| --description <description> | text | — | Longer note about the source. |
| --at <at> | text | — | Default position inside the source: text:HEADING[,NEXT] \| page:47 \| sheet:Name!A1:B9 \| row:1042 \| col:arr \| t:00:14:32 \| anchor:id. text: becomes a #:~:text= jump, so HEADING is copied verbatim from the page and NEXT is the text immediately after it. |
| --mirror <mirror> | text | — | A copy of the original stored in this project, by file name (`ingest cn extract` returns it as mirror_file). Never an address: --locator stays the original. |
| --effective-date <effective_date> | text | — | ISO date the source describes. |
| --retrieved-at <retrieved_at> | text | — | ISO timestamp it was fetched. |
| --issuer <issuer> | text | — | Who published it. |
| --ticker <issuer_ticker> | text | — | Issuer ticker symbol. |
| --identity <identities> | text | — | Declared identity as 'scheme:value' (e.g. 'sec.accession:0000320193-25-000079'). Repeatable. |
| --items <item_refs> | text | — | Rows this source backs: item ids, @order values or lo-hi order ranges (the itemOrders grammar). |
| --contexts <context_refs> | text | — | CSV of contextRefs; 'A..B' is a range in context order. Omit to cover every context the statusRef allows. |
| --status <status_ref> | text | — | statusRef for the coverage row. |
| --scenario <scenario_ref> | text | — | scenarioRef for the coverage row. |
| --custom-dimensions <custom_dimensions> | text | — | 'dim:member;dim:member' for the coverage row. |
| --index <index> | integer | — | Position (omit to append at end). |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs add-status

Add a StatusDefinition.

deepcell defs add-status <filename>
```bash
deepcell defs add-status model.deepcell --name Budget --ref budget --archetype budget --authority derived
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --name <name> | text | — | The status IDENTIFIER (@statusId), e.g. 'Forecast' — not a display label. Must satisfy the reference-id grammar. Set the readable name afterwards with `defs update-status --label`. |
| --ref <status_ref> | text | — | The status IDENTIFIER (@statusId) under the op's wire name, statusRef — the same thing as --name. If both are given, --ref wins. |
| --color <color> | text | — | (unsupported) color is a FormatDefinitions concern — see `deepcell defs add-format`. |
| --is-default | boolean | — | Mark as the document's default status — clears @isDefault from every other status. |
| --archetype <archetype> | text | — | What this status MEANS: actual \| preliminary \| restated \| estimate \| guidance \| consensus \| forecast \| budget \| plan \| target. Its realized/expected nature is derived from it. Omitting it leaves the meaning to be guessed from the id's spelling — see `deepcell ref status`. |
| --assurance <assurance> | text | — | Optional refinement: audited \| reviewed \| unaudited. |
| --authority <authority> | text | — | Optional refinement — who asserted the number: reported \| derived \| guidance \| consensus \| third_party. |
| --index <index> | integer | — | Position (omit to append at end). |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs apply

Apply a batch of ops atomically.

deepcell defs apply <filename>
```bash
deepcell defs apply model.deepcell --ops-file ops.json --dry-run
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --ops-file <ops_file> | file | — | JSON file with an `ops` array of `{"kind": …}` objects (use '-' for stdin). |
| --ops <ops_inline> | text | — | Inline ops JSON (same shapes as --ops-file); mirrors the agent tool's `defs apply --ops '<json>'` form. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --rebase-on-stale | boolean | — | If the file moved since the pinned revision, still apply the batch on the current one unless it changes something the commits in between also changed (then a 409 names the collision). A read-pinned write (no --revision) always rebases; this flag makes an explicit --revision rebase too. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs delete-axis-member

Remove a row or a column from a Block.

deepcell defs delete-axis-member <filename> --sheet <sheet_id> --block <block_id> --axis <axis> --ref <ref>
```bash
deepcell defs delete-axis-member model.deepcell --sheet variance --block revenue_table --axis rows --ref Gross_Profit
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --sheet <sheet_id> | text | 必填 | Sheet containing the block. |
| --block <block_id> | text | 必填 | blockId to edit. |
| --axis <axis> | rows \| columns | 必填 | Which axis to edit: 'rows' (the block's @itemOrders) or 'columns' (its @contextRefs). |
| --member <member> | item \| context | — | Optional, as on add-axis-member: what kind of id --ref is. Checked against --axis ('item' with rows, 'context' with columns). |
| --ref <ref> | text | 必填 | The item id or context id to remove. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs delete-block

Delete a Block from a Sheet, with the rows and columns it laid out.

deepcell defs delete-block <filename> --sheet <sheet_id> --block <block_id>
```bash
deepcell defs delete-block model.deepcell --sheet <sheet_id> --block <block_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --sheet <sheet_id> | text | 必填 | Sheet containing the block. |
| --block <block_id> | text | 必填 | blockId to delete. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs delete-calc

Delete a CalculationDefinition by calcId (`defs list` shows the ids).

deepcell defs delete-calc <filename> <calc_id>
```bash
deepcell defs delete-calc model.deepcell <calc_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| calc_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs delete-context

Delete a Context (period or non-temporal axis member).

deepcell defs delete-context <filename> <context_ref>
```bash
deepcell defs delete-context model.deepcell <context_ref>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| context_ref | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs delete-dimension

Delete a custom Dimension and its members.

deepcell defs delete-dimension <filename> <dimension_id>
```bash
deepcell defs delete-dimension model.deepcell <dimension_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| dimension_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs delete-doc

Delete a Document and its body.

deepcell defs delete-doc <filename> <doc_id>
```bash
deepcell defs delete-doc model.deepcell <doc_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| doc_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs delete-format

Delete a <Format> by formatId.

deepcell defs delete-format <filename> <format_id>
```bash
deepcell defs delete-format model.deepcell <format_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| format_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs delete-item

Delete an item, and with --cascade its descendants too.

deepcell defs delete-item <filename> <item_id>
```bash
deepcell defs delete-item model.deepcell Revenue --cascade
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| item_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --cascade | boolean | — | Also delete all descendants. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs delete-member

Delete one Member of a custom Dimension.

deepcell defs delete-member <filename> <dimension_id> <member_id>
```bash
deepcell defs delete-member model.deepcell <dimension_id> <member_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| dimension_id | text | 必填 |
| member_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs delete-rule

Delete a <Rule> by index or by @target.

deepcell defs delete-rule <filename> <format_id>
```bash
deepcell defs delete-rule model.deepcell <format_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| format_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --index <index> | integer | — | Delete the rule at this 0-based position. Exclusive with --target. |
| --target <target> | text | — | Delete the first rule with this @target. Exclusive with --index. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs delete-scenario

Delete a ScenarioDefinition by its scenarioId.

deepcell defs delete-scenario <filename> <scenario_ref>
```bash
deepcell defs delete-scenario model.deepcell <scenario_ref>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| scenario_ref | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs delete-sheet

Delete a presentation Sheet and every Block on it.

deepcell defs delete-sheet <filename> <sheet_id>
```bash
deepcell defs delete-sheet model.deepcell <sheet_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| sheet_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs delete-source

Remove a <Source>.

deepcell defs delete-source <filename> --id <source_id>
```bash
deepcell defs delete-source model.deepcell --id <source_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --id <source_id> | text | 必填 | sourceId to delete. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs delete-status

Delete a StatusDefinition by its statusId.

deepcell defs delete-status <filename> <status_ref>
```bash
deepcell defs delete-status model.deepcell <status_ref>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| status_ref | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs header set

Set or replace a <Metadata> property.

deepcell defs header set <filename> <key> <value>
```bash
deepcell defs header set model.deepcell <key> <value>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| key | text | 必填 |
| value | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --type <prop_type> | string \| number \| boolean \| datetime | string | Property type tag written into <Property @type>. The value must read as it — a number, true/false, an ISO 8601 date — or the set is refused. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs header unset

Delete a <Metadata> property.

deepcell defs header unset <filename> <key>
```bash
deepcell defs header unset model.deepcell <key>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| key | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs list

List what the document DEFINES: items, calcs, contexts, scenarios, statuses.

deepcell defs list <filename>
```bash
deepcell defs list model.deepcell
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --kind <kind> | text | — | Only these sections: item, calc, context, scenario, status (plurals work; repeat the flag or comma-separate). |
| --item <item> | text | — | Only these items, and only the calcs computing them — the calc ids `defs update-calc` / `delete-calc` quote. Alone, lists just those two sections. |
| --workspace <workspace_slug> | text | — | Override active workspace. |

退出码： 0 — completed · 1 — read-only-check

#### defs merge-sections

Store each top-level section once (fixes `duplicate_section`).

deepcell defs merge-sections <filename>
```bash
deepcell defs merge-sections model.deepcell --keep last
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --keep <keep> | both \| first \| last | both | For an id two copies define differently: refuse and name it (both), or keep the earlier (first) or later (last) section's version. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs rename-block

Change a Block's display name — its section heading in the render.

deepcell defs rename-block <filename> <new_name> --sheet <sheet_id> --block <block_id>
```bash
deepcell defs rename-block model.deepcell <new_name> --sheet <sheet_id> --block <block_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| new_name | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --sheet <sheet_id> | text | 必填 | Sheet containing the block. |
| --block <block_id> | text | 必填 | blockId to rename. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs rename-context

Rename a Context's @contextId; references cascade.

deepcell defs rename-context <filename> <context_ref> <new_name>
```bash
deepcell defs rename-context model.deepcell <context_ref> <new_name>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| context_ref | text | 必填 |
| new_name | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs rename-dimension

Rename a custom Dimension's @dimensionId.

deepcell defs rename-dimension <filename> <dimension_id> <new_name>
```bash
deepcell defs rename-dimension model.deepcell <dimension_id> <new_name>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| dimension_id | text | 必填 |
| new_name | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs rename-item

Rename an item's stable identifier; references cascade.

deepcell defs rename-item <filename> <item_id> <new_name>
```bash
deepcell defs rename-item model.deepcell Revenue Total_Revenue
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| item_id | text | 必填 |
| new_name | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs rename-member

Rename one Member's @memberId within a custom Dimension.

deepcell defs rename-member <filename> <dimension_id> <member_id> <new_name>
```bash
deepcell defs rename-member model.deepcell <dimension_id> <member_id> <new_name>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| dimension_id | text | 必填 |
| member_id | text | 必填 |
| new_name | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs rename-scenario

Rename a scenario's IDENTIFIER (@scenarioId); references cascade.

deepcell defs rename-scenario <filename> <scenario_ref> <new_name>
```bash
deepcell defs rename-scenario model.deepcell downside bear
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| scenario_ref | text | 必填 |
| new_name | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs rename-sheet

Change a Sheet's displayed tab label.

deepcell defs rename-sheet <filename> <sheet_id> <new_label>
```bash
deepcell defs rename-sheet model.deepcell <sheet_id> <new_label>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| sheet_id | text | 必填 |
| new_label | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs rename-status

Change a status's IDENTIFIER (@statusId); references cascade.

deepcell defs rename-status <filename> <status_ref> <new_name>
```bash
deepcell defs rename-status model.deepcell <status_ref> <new_name>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| status_ref | text | 必填 |
| new_name | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs reorder-axis-member

Move a row or a column to a new position within a Block.

deepcell defs reorder-axis-member <filename> --sheet <sheet_id> --block <block_id> --axis <axis> --ref <ref> --to-index <to_index>
```bash
deepcell defs reorder-axis-member model.deepcell --sheet variance --block revenue_table --axis rows --ref Gross_Profit --to-index 0
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --sheet <sheet_id> | text | 必填 | Sheet containing the block. |
| --block <block_id> | text | 必填 | blockId to edit. |
| --axis <axis> | rows \| columns | 必填 | Which axis to edit: 'rows' (the block's @itemOrders) or 'columns' (its @contextRefs). |
| --ref <ref> | text | 必填 | The item id or context id to move. |
| --to-index <to_index> | integer range | 必填 | Final 0-based position on the axis. 0 = first row / leftmost column; an index past the end lands last. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs reorder-block

Move a Block to a new position within its Sheet.

deepcell defs reorder-block <filename> --sheet <sheet_id> --block <block_id> --to-index <to_index>
```bash
deepcell defs reorder-block model.deepcell --sheet variance --block revenue_table --to-index 0
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --sheet <sheet_id> | text | 必填 | Sheet containing the block. |
| --block <block_id> | text | 必填 | blockId to move. |
| --to-index <to_index> | integer range | 必填 | Final 0-based position among the sheet's blocks. 0 = topmost; an index past the end lands last. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs reorder-contexts

Move a Context to a new position in context order (TO_INDEX, 0-based).

deepcell defs reorder-contexts <filename> <context_ref> <to_index>
```bash
deepcell defs reorder-contexts model.deepcell <context_ref> <to_index>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| context_ref | text | 必填 |
| to_index | integer | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs reorder-item

Move an item to a new position among its siblings (final-position index).

deepcell defs reorder-item <filename> <item_id> --to-index <to_index>
```bash
deepcell defs reorder-item model.deepcell Revenue --to-index 0
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| item_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --to-index <to_index> | integer | 必填 | Final 0-based position among the item's siblings. 0 = first. Lets you place a referenced item before its referencer (avoids a forward item-order reference). |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs reorder-scenarios

Move a scenario to a new position in the scenario list.

deepcell defs reorder-scenarios <filename> <scenario_ref> --to-index <to_index>
```bash
deepcell defs reorder-scenarios model.deepcell <scenario_ref> --to-index <to_index>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| scenario_ref | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --to-index <to_index> | integer range | 必填 | Final 0-based position among the scenarios. 0 = first. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs reorder-sheets

Move a Sheet to a new position in the tab order.

deepcell defs reorder-sheets <filename> <sheet_id> --to-index <to_index>
```bash
deepcell defs reorder-sheets model.deepcell variance --to-index 0
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| sheet_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --to-index <to_index> | integer range | 必填 | Final 0-based position among the sheets. 0 = leftmost tab; an index past the end lands last. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs set-block-attrs

Set presentation-layout attributes on an existing block.

deepcell defs set-block-attrs <filename> --sheet <sheet_id> --block <block_id>
```bash
deepcell defs set-block-attrs model.deepcell --sheet variance --block revenue_table --status-refs actual,budget --status-expansion columns
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --sheet <sheet_id> | text | 必填 | Sheet containing the block. |
| --block <block_id> | text | 必填 | blockId of the block to edit. |
| --format-ref <format_ref> | text | — | FormatDefinitions id this block resolves against. Pass an empty string to clear it back to the document default (the Format named default_format, else the first one defined). The id is not checked: one no Format defines is stored and the block silently takes that same default. See `deepcell ref format`. |
| --status-expansion <status_expansion> | none \| columns \| series | — | Side-by-side status-column layout. 'columns' lays each status in --status-refs out as its own run of context columns; 'series' is the chart form, one series per status; 'none' (default) keeps the single-column-per-context layout. |
| --status-refs <status_refs> | text | — | Whitespace/comma-separated status ids to expand into columns (e.g. "actual budget"). Required for --status-expansion=columns. |
| --dim-expansion <dim_expansion> | none \| rows \| series | — | Custom-dimension member sub-rows. 'rows' lays each member of --dim-ref out as a contiguous sub-row under its item; 'series' is the chart form, one series per member; 'none' (default) keeps the one-row-per-item layout. |
| --dim-ref <dim_ref> | text | — | Dimension id whose members are expanded into sub-rows (e.g. "geography"). Required for --dim-expansion=rows. |
| --dim-expansion-cap <dim_expansion_cap> | integer range | — | Max members to expand into sub-rows before falling back to a single row (positive int; default 24). Used with --dim-expansion=rows. |
| --dim-member-refs <dim_member_refs> | text | — | Whitespace/comma-separated member ids of --dim-ref, order preserved. With --dim-expansion it selects which members expand; without one, a single id pins that member for every cell the block reads — how a chart plots one slice of a dimension-sliced item. |
| --dim-filter <dim_filter> | text | — | Pin the dimensions the block does NOT expand, one member each: 'region:na;cohort:c1'. Same dim:member spelling and ';' separator as customDimensions on a Value, so a stored coordinate can be copied across. A block expands one dimension (--dim-ref), so this is what makes a cell keyed on two or more custom dimensions addressable. |
| --scenario-expansion <scenario_expansion> | none \| columns \| series | — | Side-by-side scenario-column layout. 'columns' lays each scenario in --scenario-refs out as its own run of context columns; 'series' is the chart form, one series per scenario; 'none' (default) keeps the single-column-per-context layout. |
| --scenario-refs <scenario_refs> | text | — | Whitespace/comma-separated scenario ids to expand into columns (e.g. "Base Bull"). Required for --scenario-expansion=columns. |
| --chart-type <chart_type> | text | — | — |
| --category-axis <category_axis> | text | — | — |
| --chart-spec <chart_spec> | text | — | The chart, as a JSON object (chart blocks; a chart block written without one draws its selection as grouped columns). Compact: {"family":"line","series":[{"itemRef":"Revenue"}]} over the block's contexts, with categoryAxis, arrangement, totalItemRefs and the Block's ref attributes; {} charts the block's selection. Families: column (vertical), bar (horizontal), line, area, waterfall, range_bar, scatter, pie, doughnut, funnel, radar. Explicit: with "data". Inspect with `deepcell query --chart-details`. |
| --clear-chart-spec | boolean | — | — |
| --chart-annotations <chart_annotations> | text | — | — |
| --total-item-refs <total_item_refs> | text | — | — |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs set-format

Set cell/row/column formatting: upsert one <Rule> in the governing <Format>.

deepcell defs set-format <filename> --sheet-id <sheet_id> --scope <scope>
```bash
deepcell defs set-format model.deepcell --sheet-id ic --block-id deal_summary --item-ref Entry_Multiple --scope item --number-format '0.0x' --bold
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --sheet-id <sheet_id> | text | 必填 | Sheet id of the cell. Recorded with the op; the Format is found through --block-id, not the sheet. |
| --block-id <block_id> | text | — | Block whose @formatRef names the Format to write into. Omit for the document default (default_format, else the first Format; created as default_format when none exists). |
| --item-ref <item_ref> | text | — | Item ref (required for --scope cell and item; unused for context). |
| --context-ref <context_ref> | text | — | Context ref (required for cell/column scope). |
| --scope <scope> | cell \| item \| context | 必填 | cell:ITEM:CONTEXT \| item:ITEM \| context:CONTEXT |
| --number-format <number_format> | text | — | Excel pattern, all three sections, e.g. '#,##0.0;(#,##0.0);"-"' (`deepcell ref format/pattern`). |
| --font-name <font_name> | text | — | Font family name. |
| --font-size <font_size> | float | — | Font size in points. |
| --bold | boolean | — | Set/clear bold. |
| --italic | boolean | — | Set/clear italic. |
| --fg-color <fg_color> | text | — | Text hex '#RRGGBB'. |
| --bg-color <bg_color> | text | — | Fill hex '#RRGGBB'. |
| --text-align <text_align> | text | — | 'left'\|'center'\|'right'. |
| --indent <indent> | integer | — | Indent character count. |
| --border-top <border_top> | text | — | e.g. 'thin #000000'. |
| --border-bottom <border_bottom> | text | — | Bottom border, e.g. 'thin #000000' (style + optional hex color). |
| --border-left <border_left> | text | — | Left border, e.g. 'thin #000000' (style + optional hex color). |
| --border-right <border_right> | text | — | Right border, e.g. 'thin #000000' (style + optional hex color). |
| --clear <clear> | text | — | Token name to revert to inherit (repeatable). |
| --clear-all | boolean | — | Delete the target's rule entirely. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs set-source-cites

Replace which cells a <Source> backs, or add a row with --append.

deepcell defs set-source-cites <filename> --id <source_id>
```bash
deepcell defs set-source-cites model.deepcell --id <source_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --id <source_id> | text | 必填 | sourceId whose coverage to set. |
| --items <item_refs> | text | — | Rows this source backs: item ids, @order values or lo-hi order ranges (the itemOrders grammar). |
| --contexts <context_refs> | text | — | CSV of contextRefs; 'A..B' is a range in context order. Omit to cover every context the statusRef allows. |
| --status <status_ref> | text | — | statusRef for the coverage row. |
| --scenario <scenario_ref> | text | — | scenarioRef for the coverage row. |
| --custom-dimensions <custom_dimensions> | text | — | 'dim:member;dim:member' for the coverage row. |
| --at <at> | text | — | Position override for this coverage row (grammar: add-source --at). |
| --append | boolean | — | Add this row to the existing coverage instead of replacing it. A row the source already holds (same five axes and --at) is a no-op. |
| --clear | boolean | — | Remove every coverage row instead of setting one. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs show

Show one item's ItemDef and every CalcDef that governs it.

deepcell defs show <filename> <item_id>
```bash
deepcell defs show model.deepcell Revenue
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| item_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --workspace <workspace_slug> | text | — | Override active workspace. |

退出码： 0 — completed · 1 — read-only-check

#### defs update-calc

Patch a CalcDef; only the fields you pass are changed.

deepcell defs update-calc <filename> <calc_id>
```bash
deepcell defs update-calc model.deepcell calc_revenue --formula 'Units_Sold[CURRENT] * Unit_Price[CURRENT] * 1.02'
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| calc_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --formula <formula> | text | — | Replace the formula. |
| --context <context_ref> | text | — | Replace the periods the calc writes (@contextRefs): one id, a CSV, or an 'A..B' range in context order. Pass '' to clear — the calc then writes every period. Cells it no longer writes are retired. |
| --scenario <scenario_ref> | text | — | Change scenarioRef. Pass '' to clear. |
| --status <status_ref> | text | — | Change statusRef (e.g. 'projected'). Pass '' to clear. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs update-context

Patch a Context's id, label, status, kind, state, as-of date, or period shape (granularity, start/end dates, parent); only the fields you pass are sent.

deepcell defs update-context <filename> <context_ref>
```bash
deepcell defs update-context model.deepcell FY2025 --state closed --as-of 2025-12-31
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| context_ref | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --name <name> | text | — | Rename the contextId; references cascade. NOT the display name — see --label. |
| --label <new_label> | text | — | Change the context's DISPLAY LABEL (emits set_context_label). The contextId is untouched — use --name to change the identifier. |
| --status <status_ref> | text | — | Set statusRef. |
| --clear-status | boolean | — | Clear statusRef (explicit-null). |
| --kind <kind> | text | — | Context kind. Omit / null / 'period' / temporal alias collapses to canonical 'period'; any other snake_case label marks a non-temporal context. Always written to @kind. |
| --state <state> | text | — | Period state: closed \| open \| future. This is what says whether the period is over — never the A/E suffix on a context id. Only meaningful for --kind period. |
| --as-of <as_of> | text | — | ISO YYYY-MM-DD the period's numbers are stated as of. Documentation and lint input only; never consulted when rendering. |
| --granularity <granularity> | text | — | Period length: annual \| semiannual \| quarterly \| monthly (written as <Type>). Growth, margin and CAGR checks compare only periods of one granularity. Pass '' to clear. |
| --start-date <start_date> | text | — | First day of the period (<StartDate>). Pass '' to clear. |
| --end-date <end_date> | text | — | Last day of the period (<EndDate>). Pass '' to clear. |
| --parent <parent_context> | text | — | The enclosing period's id, e.g. FY2026 for Q1_2026 (@parentContext); SUM_CHILDREN sums over it. Pass '' to clear. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs update-doc

Update a Document's attributes.

deepcell defs update-doc <filename> <doc_id>
```bash
deepcell defs update-doc model.deepcell <doc_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| doc_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --name <name> | text | — | New display title. |
| --lang <lang> | text | — | New BCP-47 language tag. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs update-format

Rename a <Format> and/or toggle its IB-default inheritance.

deepcell defs update-format <filename> <format_id>
```bash
deepcell defs update-format model.deepcell <format_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| format_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --new-id <new_id> | text | — | New formatId; cascades through every <Block @formatRef>. |
| --inherit | boolean | — | Toggle the IB default base. --no-inherit makes this a total custom theme (@inherit="false"); --inherit returns to the add-on default. See `deepcell ref format`. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs update-item

Patch an item; only fields you pass are sent.

deepcell defs update-item <filename> <item_id>
```bash
deepcell defs update-item model.deepcell Revenue --scale 3 --currency USD
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| item_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --name <name> | text | — | Rename the itemId; references cascade. Equivalent to `defs rename-item`. |
| --label <new_label> | text | — | Change the item's DISPLAY LABEL (emits set_item_label). The itemId is untouched — use `defs rename-item` to change the identifier. Rewrites the text of the item's first <Label> and keeps its lang; other locales are left alone and cannot be added here. |
| --level <level> | integer | — | Change hierarchy level. |
| --parent <parent_item_id> | text | — | Change parent itemId. |
| --clear-parent | boolean | — | Make item a root (explicit-null parentItemId). |
| --data-type <data_type> | text | — | Set DataType element (e.g. 'monetary', 'percentage', 'number'). |
| --unit <unit> | text | — | Set Unit element (e.g. '%', 'hours', 'tonnes'). |
| --scale <scale> | integer | — | Set Scale element — monetary only; on another type it changes no display digits (see add-item --scale). |
| --currency <currency> | text | — | Set Currency element: an ISO 4217 code, or 'XXX' when the source states none. |
| --shape <shape> | scalar \| period | — | Declare the item's one shape (@shape): 'scalar' = only Item[] cells, 'period' = a value per period. Refused, naming the cells, while the item stores a cell of the other shape in any status, scenario or member — unless --context converts them. |
| --context <context> | text | — | With --shape, convert the item's cells at this period, in every status, scenario and member: --shape period moves Item[] to Item[CONTEXT]; --shape scalar makes Item[CONTEXT] the scalar Item[] and deletes every other period's cell (listed in the result). Required when the item holds cells of the other shape. |
| --clear-data-type | boolean | — | Remove the DataType element (explicit-null). |
| --clear-unit | boolean | — | Remove the Unit element (explicit-null). |
| --clear-scale | boolean | — | Remove the Scale element (explicit-null). |
| --clear-currency | boolean | — | Remove the Currency element (explicit-null). |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs update-scenario

Patch a scenario; only the fields you pass are sent.

deepcell defs update-scenario <filename> <scenario_ref>
```bash
deepcell defs update-scenario model.deepcell downside --label 'Bear case'
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| scenario_ref | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --name <name> | text | — | Rename the scenarioId; references cascade. Equivalent to `defs rename-scenario`. NOT the display name — see --label. |
| --label <new_label> | text | — | Change the scenario's DISPLAY LABEL (emits set_scenario_label). The scenarioId is untouched — use --name to change the identifier. |
| --is-default | boolean | — | Make this the document's default scenario (clears @isDefault from every other scenario), or strip the flag from this one. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs update-sensitivity

Edit a sensitivity block's name, format, or axes/outputs.

deepcell defs update-sensitivity <filename> --sheet <sheet_id> --block <block_id>
```bash
deepcell defs update-sensitivity model.deepcell --sheet <sheet_id> --block <block_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --sheet <sheet_id> | text | 必填 | Sheet containing the block. |
| --block <block_id> | text | 必填 | blockId of the block to edit. |
| --name <name> | text | — | New display name. |
| --format-ref <format_ref> | text | — | New FormatDefinitions id. |
| --spec-file <spec_file> | file | — | JSON with {"axes": [...], "outputs": [...]} to replace both. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs update-source

Change fields on a <Source>.

deepcell defs update-source <filename> --id <source_id>
```bash
deepcell defs update-source model.deepcell --id <source_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --id <source_id> | text | 必填 | sourceId to update. |
| --kind <kind> | text | — | New @kind (closed set). |
| --role <role> | text | — | New @role (free text). |
| --reach <reach> | text | — | public \| account \| private \| offline. |
| --title <title> | text | — | New title. Pass '' to clear. |
| --locator <locator> | text | — | New locator. Pass '' to clear. |
| --mirror <mirror> | text | — | New project copy, by file name. Pass '' to clear. |
| --description <description> | text | — | New description. Pass '' to clear. |
| --at <at> | text | — | New default position (grammar: add-source --at). |
| --effective-date <effective_date> | text | — | New effective date. |
| --retrieved-at <retrieved_at> | text | — | New retrieval timestamp. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### defs update-status

Patch a status; only the fields you pass are sent.

deepcell defs update-status <filename> <status_ref>
```bash
deepcell defs update-status model.deepcell budget --archetype budget --label Budget
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| status_ref | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --name <name> | text | — | Rename the statusId; references cascade. Equivalent to `defs rename-status`. NOT the display name — see --label. |
| --label <new_label> | text | — | Change the status's DISPLAY LABEL (emits set_status_label). The statusId is untouched — use --name to change the identifier. |
| --is-default | boolean | — | Make this the document's default status (clears @isDefault from every other status), or strip the flag from this one. |
| --archetype <archetype> | text | — | What this status MEANS: actual \| preliminary \| restated \| estimate \| guidance \| consensus \| forecast \| budget \| plan \| target. Pass an empty string to clear it (and fall back to inference). |
| --assurance <assurance> | text | — | audited \| reviewed \| unaudited. |
| --authority <authority> | text | — | reported \| derived \| guidance \| consensus \| third_party. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |
| --dry-run | boolean | — | Validate only: run the full server-side pipeline (per-op validation, formula parse, post-apply cycle check + recompute) and report errors without persisting anything — no commit, no revision bump. |
| --plan-delivery <plan_delivery> | none \| cache \| inline | — | What the server does with the post-edit render plan: `cache` (default) builds it after answering, into the cache the next describe or viewer read uses — except a batch touching a slide, binding or deck style, whose plan is built before answering to measure fit; `inline` builds it before answering and returns it (slower). A write that built its plan prints the orphan / status-clash warnings and only the conversion warnings it introduced; otherwise the next `describe` reports them. `none` builds nothing. |
| --measure-fit | boolean | — | Measure the slides this batch touched with the deck exporter (default on; never under --plan-delivery none). --no-measure-fit skips the round trip. |

退出码： 0 — completed · 1 — nothing-changed

#### doc backlinks

Show what cites a reference: prose, slides and reasoning, this file only.

deepcell doc backlinks <filename> --target <target>
```bash
deepcell doc backlinks model.deepcell --target <target>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --target <target> | text | 必填 | Reference to invert, e.g. 'claim/t_hold'. |

退出码： 0 — completed

#### doc blocks

List every block and the id it can be edited by.

deepcell doc blocks <filename> [doc_positional]
```bash
deepcell doc blocks model.deepcell
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| doc_positional | text | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --doc <doc_id> | text | — | Document ID (default: the first); also accepted as the second argument. |

退出码： 0 — completed

#### doc brand

Recolour a document, or change its faces, by ROLE without touching its stylesheet.

deepcell doc brand <filename> --doc <doc_id>
```bash
deepcell doc brand model.deepcell --doc <doc_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --doc <doc_id> | text | 必填 | Document to recolour. |
| --set <assignments> | text | — | Role override, repeatable: --set accent=#7A1F2B --set font-text=Georgia. Colours: accent (headings), ink (text), muted (captions, quotes), rule, surface (table header ground); faces: font-display (headings), font-text (a safe face, `deepcell ref deck-style/fonts`), font-cjk (Microsoft YaHei, SimSun, SimHei, DengXian, Microsoft JhengHei). |
| --clear | boolean | — | Remove the brand; the pack's own colours and faces show again. |
| --rationale <rationale> | text | — | Commit message recording why. |
| --revision <revision> | text | — | Compare-and-swap token from `cat`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed

#### doc delete-block

Delete one block.

deepcell doc delete-block <filename> --doc <doc_id> --block <block_id>
```bash
deepcell doc delete-block model.deepcell --doc <doc_id> --block <block_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --doc <doc_id> | text | 必填 | Document ID. |
| --block <block_id> | text | 必填 | Block id to delete. |
| --rationale <rationale> | text | — | Commit message recording why. |
| --revision <revision> | text | — | Compare-and-swap token from `cat`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed

#### doc insert-block

Insert a new block after another one, or at the top of the document.

deepcell doc insert-block <filename> --doc <doc_id> --markdown-file <markdown_file>
```bash
deepcell doc insert-block model.deepcell --doc <doc_id> --markdown-file <markdown_file>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --doc <doc_id> | text | 必填 | Document ID. |
| --after <after_block_id> | text | — | Insert after this block id. Omit to insert at the top. |
| --markdown-file <markdown_file> | file | 必填 | File holding the new block's markdown; `-` reads stdin. |
| --rationale <rationale> | text | — | Commit message recording why. |
| --revision <revision> | text | — | Compare-and-swap token from `cat`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed

#### doc links

List every deepcell: reference, and whether it resolved.

deepcell doc links <filename>
```bash
deepcell doc links model.deepcell --doc variance_note --unresolved
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --doc <doc_id> | text | — | Restrict to one document. |
| --unresolved | boolean | — | Only references that did not resolve. |

退出码： 0 — completed

#### doc lint

Check a document's references.

deepcell doc lint <filename>
```bash
deepcell doc lint model.deepcell --doc variance_note --strict
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --doc <doc_id> | text | — | Restrict to one document. |
| --strict | boolean | — | Also flag numerals that match a modelled value but are typed, not linked. |

退出码： 0 — completed

#### doc list

List every <Document> in the file.

deepcell doc list <filename>
```bash
deepcell doc list model.deepcell
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

退出码： 0 — completed

#### doc move-block

Move a block after another one, or to the top.

deepcell doc move-block <filename> --doc <doc_id> --block <block_id>
```bash
deepcell doc move-block model.deepcell --doc <doc_id> --block <block_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --doc <doc_id> | text | 必填 | Document ID. |
| --block <block_id> | text | 必填 | Block id to move. |
| --after <after_block_id> | text | — | Move after this block id. Omit to move to the top. |
| --rationale <rationale> | text | — | Commit message recording why. |
| --revision <revision> | text | — | Compare-and-swap token from `cat`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed

#### doc outline

Print the headings and the anchor each one is addressable by.

deepcell doc outline <filename>
```bash
deepcell doc outline model.deepcell --doc variance_note
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --doc <doc_id> | text | — | Document ID (default: the first). |

退出码： 0 — completed

#### doc patch-body

Replace one anchored block, or a heading's whole section.

deepcell doc patch-body <filename> --doc <doc_id> --anchor <anchor>
```bash
deepcell doc patch-body model.deepcell --doc variance_note --anchor outlook --markdown '## Outlook {#outlook}\n\nQ4 pipeline covers the gap.'
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --doc <doc_id> | text | 必填 | Document ID. |
| --anchor <anchor> | text | 必填 | Explicit {#id} anchor of the block or section to replace. |
| --scope <scope> | block \| section | — | `block`: the anchored block alone. `section`: a heading and every block under it (an H1 at the top owns the whole document). Omitted, a heading with blocks under it is refused rather than guessed. |
| --markdown <markdown> | text | — | Replacement markdown. |
| --markdown-file <markdown_file> | file | — | File holding the replacement markdown; `-` reads stdin. A section is paragraphs, so this is the form a shell quote will not mangle. `--body-file` is the same option, spelled as `set-body` spells it. |
| --notation <notation> | markdown \| text | — | What the body IS. Omitted keeps whatever the document already declared, so editing text never retypes it. |
| --rationale <rationale> | text | — | Commit message recording why. |
| --revision <revision> | text | — | Compare-and-swap token from `cat`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed

#### doc render-block

Sanitize one deepcell-html fence and show what it keeps and refuses.

```bash
deepcell doc render-block --source-file <source_file>
```

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --source-file <source_file> | file | 必填 | A file holding the body of one deepcell-html fence; `-` reads stdin. |
| --file <filename> | text | — | Workspace file whose decks the style cascade may inherit from. |
| --deck <deck_ref> | text | — | Deck whose <Style> the block inherits; needs --file, which defines it. |

退出码： 0 — completed

#### doc replace-block

Replace one block, addressed by its id.

deepcell doc replace-block <filename> --doc <doc_id> --block <block_id> --markdown-file <markdown_file>
```bash
deepcell doc replace-block model.deepcell --doc <doc_id> --block <block_id> --markdown-file <markdown_file>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --doc <doc_id> | text | 必填 | Document ID. |
| --block <block_id> | text | 必填 | Block id from `deepcell doc blocks`. |
| --markdown-file <markdown_file> | file | 必填 | File holding the replacement markdown; `-` reads stdin. |
| --rationale <rationale> | text | — | Commit message recording why. |
| --revision <revision> | text | — | Compare-and-swap token from `cat`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed

#### doc set-body

Replace a document's whole body.

deepcell doc set-body <filename> --doc <doc_id> --body-file <body_file>
```bash
deepcell doc set-body model.deepcell --doc variance_note --body-file variance-note.md -m 'Rewrite the July variance note'
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --doc <doc_id> | text | 必填 | Document ID. |
| --body-file <body_file> | file | 必填 | File holding the new body; `-` reads stdin. |
| --notation <notation> | markdown \| text | — | What the body IS. Omitted keeps whatever the document already declared, so editing text never retypes it. |
| --allow-empty | boolean | — | Allow an empty body to replace one that has blocks. Without it that write is refused (document_body_empty). |
| --rationale <rationale> | text | — | Commit message recording why. |
| --revision <revision> | text | — | Compare-and-swap token from `cat` (refuses if the file moved). |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed

#### doc set-notation

Say what a document's body IS, without touching a byte of it.

deepcell doc set-notation <filename> --doc <doc_id> --notation <notation>
```bash
deepcell doc set-notation model.deepcell --doc <doc_id> --notation <notation>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --doc <doc_id> | text | 必填 | Document ID. |
| --notation <notation> | markdown \| text | 必填 | What the body IS. |
| --rationale <rationale> | text | — | Commit message recording why. |
| --revision <revision> | text | — | Compare-and-swap token from `cat`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed

#### doc show

Print one document.

deepcell doc show <filename> [doc_positional]
```bash
deepcell doc show model.deepcell --doc variance_note --as markdown
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| doc_positional | text | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --doc <doc_id> | text | — | Document ID (default: the first); also accepted as the second argument. |
| --scenario <scenario_id> | text | — | Scenario to resolve values under. |
| --as <rendering> | text \| markdown | text | markdown keeps the [[deepcell:...]] source; text shows resolved values. |
| --with-ids | boolean | — | Prefix each block with the id it can be edited by. |

退出码： 0 — completed

#### doc stamp-ids

Give every block without an id a stable `{#id}`, so it can be edited.

deepcell doc stamp-ids <filename> --doc <doc_id>
```bash
deepcell doc stamp-ids model.deepcell --doc <doc_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --doc <doc_id> | text | 必填 | Document ID. |
| --rationale <rationale> | text | — | Commit message recording why. |
| --revision <revision> | text | — | Compare-and-swap token from `cat`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed

#### doc style

Set a document's stylesheet: a PACK, a CSS file, or just the paper.

deepcell doc style <filename> --doc <doc_id>
```bash
deepcell doc style model.deepcell --doc <doc_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --doc <doc_id> | text | 必填 | Document to restyle. |
| --pack <pack> | text | — | A document style pack — report, classic, office, chinese-formal (`deepcell ref doc-style`). Its CSS is copied into the document's <Style>. |
| --keep-own-rules | boolean | — | With --pack: keep the rules written after the old pack (the document's own, such as its paper) and replace only the pack. |
| --css-file <css_file> | file | — | The document's own stylesheet, whole (`-` reads stdin). Replaces, never merges. |
| --page <page> | letter \| a4 \| legal \| a5 | — | Paper size for the PDF and .docx. Alone, it changes only the paper of the sheet already stored. |
| --clear | boolean | — | Remove the document's <Style>: the panel's default look. |
| --rationale <rationale> | text | — | Commit message recording why. |
| --revision <revision> | text | — | Compare-and-swap token from `cat`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed

#### edit

Set or change literal cell values (assumptions, historical actuals).

deepcell edit <filename> [item_ref] [context_ref] [new_value]
```bash
deepcell edit model.deepcell Growth_Rate FY2026E 0.12
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| item_ref | text | 可选 |
| context_ref | text | 可选 |
| new_value | text | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --force | boolean | — | Type over a calculated cell, REMOVING the formula that computed it (no in-document undo). |
| --clear | boolean | — | Remove the literal value cell (NEW_VALUE omitted) so a CalcDef can re-govern it. |
| --status <status_ref> | text | — | Status reference (e.g. 'projected'). |
| --scenario <scenario_ref> | text | — | Scenario dimension — must be a defined scenarioId (omit for the base cell). |
| --custom-dimensions <custom_dimensions> | text | — | Custom dimensions as 'dim:member;dim:member', e.g. 'geography:na;product_line:ent'. |
| --batch <batch_file> | text | — | Batch edits as a JSON file path, '-' for stdin, or inline JSON (a value starting with '[' or '{'). |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --rationale <commit_message> | text | — | Why this edit was made. Written as the commit message body (and a trailer), so history reads as the decision instead of 'Edited Revenue (FY2025)'. Sent as `rationale`; `-m` / `--message` are aliases of `--rationale`. |
| --title <commit_title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. |
| --auto-create-context | boolean | — | Auto-create missing context definitions. |
| --replace | boolean | — | DEPRECATED alias for `deepcell replace FILE OLD NEW` — still works, will be removed in a future release. Note the exit codes listed here are `edit`'s: in replace mode, exit 1 means the replacement IS already in the file and the document is invalid. |
| --replace-all | boolean | — | Replace all occurrences (with the deprecated --replace). |
| --workspace <workspace_slug> | text | — | Override active workspace. |

退出码： 0 — completed · 1 — nothing-changed

#### reasoning add-argument

Add a new <Argument> edge to FILENAME's <Reasoning> section.

deepcell reasoning add-argument <filename> --from-id <from_id> --to-id <to_id> --rel <rel>
```bash
deepcell reasoning add-argument model.deepcell --from-id r_pricing --to-id t_gm --rel refutes --weight 0.6
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --from-id <from_id> | text | 必填 | Source node id. |
| --to-id <to_id> | text | 必填 | Target node id. |
| --rel <rel> | supports \| refutes \| depends_on \| derives_from \| variant_of \| supersedes \| contradicts \| references \| answers \| asks_about | 必填 | How --from-id relates to --to-id: supports / refutes (evidential), depends_on (falsifying the target falsifies the source), derives_from (computed or inferred from it), answers (this claim settles that question), asks_about (this question probes that node), variant_of (your view vs a consensus claim), supersedes (replaces an older node), contradicts, references. See `deepcell ref rel`. |
| --id <arg_id> | text | — | Argument id (auto-generated if omitted). |
| --weight <weight> | float | — | How much this edge carries, 0-1 (optional). |
| --body <body> | text | — | <Body> text. |
| --body-file <body_file> | file | — | File holding the <Body> text; '-' reads stdin. Prefer this over --body for text containing '$' — inline shell arguments mangle dollar amounts. |
| --body-notation <body_notation> | markdown \| text | — | What the <Body> IS: markdown or literal text. Omitted keeps what the body declares; a body that declares nothing is read as markdown when it carries a markdown mark (a [[deepcell:...]] reference, **bold**, a heading) and lints as notation_inferred until it is declared. |
| --status <status> | text | — | Argument lifecycle status (active/superseded/revoked). |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed · 1 — written-but-invalid

#### reasoning add-assumption

Add a new <Assumption> to FILENAME's <Reasoning> section.

deepcell reasoning add-assumption <filename>
```bash
deepcell reasoning add-assumption model.deepcell --id a_hiring --label 'Hiring lands on plan' --body 'Sales headcount reaches 40 by Q3.' --item-refs Headcount
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --id <assumption_id> | text | — | New Assumption id. Omit to derive one from --label; the answer names it. |
| --label <label> | text | — | <Label> text. The finding itself, not the subject it concerns — "Working capital is a source of cash", not "Working capital". Renders as the reasoning outline row, and a Deck may bind it as a slide headline. |
| --label-file <label_file> | file | — | File holding the <Label> text; '-' reads stdin. Prefer this over --label for text containing '$' — inline shell arguments mangle dollar amounts. |
| --body <body> | text | — | <Body> text. |
| --body-file <body_file> | file | — | File holding the <Body> text; '-' reads stdin. Prefer this over --body for text containing '$' — inline shell arguments mangle dollar amounts. |
| --body-notation <body_notation> | markdown \| text | — | What the <Body> IS: markdown or literal text. Omitted keeps what the body declares; a body that declares nothing is read as markdown when it carries a markdown mark (a [[deepcell:...]] reference, **bold**, a heading) and lints as notation_inferred until it is declared. |
| --status-ref <status_ref> | text | — | Model Status dimension id (e.g. actual / projected) — NOT the assumption's lifecycle state (that is --status). |
| --calc-ref <calc_ref> | text | — | ONE CalcDef id anchoring this assumption to a formula (never a list). |
| --item-refs <item_refs> | text | — | Item ids the assumption constrains (or @order values / lo-hi ranges, the itemOrders grammar). When a Spreadsheet exists, omitting it triggers unanchored_assumption because the premise cannot be item-impact-traced as actuals drift in. A qualitative no-grid file and macro assumptions may legitimately omit it. |
| --confidence <confidence> | float | — | How strongly you hold this assumption, 0-1. |
| --status <status> | holding \| uncertain \| broken \| superseded | — | Assumption lifecycle state: holding until something contradicts it, broken once actuals do, superseded when a newer assumption replaces it. |
| --verified-at <verified_at> | text | — | ISO date (YYYY-MM-DD) this assumption was last confirmed to still hold (@verifiedAt). Records WHEN it was checked; --status holding records that it stands. |
| --broken-at <broken_at> | text | — | ISO date (YYYY-MM-DD) this assumption was found no longer to hold (@brokenAt). Records WHEN it failed; --status broken records THAT it failed — set both when actuals contradict an assumption. |
| --parent-claim-ref <parent_claim_ref> | text | — | Claim id this assumption hangs under (hierarchy, not an Argument edge). |
| --context-refs <context_refs> | text | — | Comma-separated context (period) ids this node reasons across; 'A..B' is a range, every period from A to B inclusive in context order (e.g. 'FY2027E..FY2031E'). 'A,B' stays two periods. |
| --scenario-ref <scenario_ref> | text | — | Scenario id this node is about, when it holds only in one world. |
| --custom-dimensions <custom_dimensions> | text | — | Custom dimension members as `dim:member;dim2:member2` — the fifth axis of the anchor (e.g. `region:emea`). |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed · 1 — written-but-invalid

#### reasoning add-claim

Add a new <Claim> to FILENAME's <Reasoning> section.

deepcell reasoning add-claim <filename> --kind <kind>
```bash
deepcell reasoning add-claim model.deepcell --id t_gm --kind thesis --label 'Gross margin expands' --body 'Mix shift to subscription lifts GM 200bps.' --item-refs Gross_Margin_Pct --confidence 0.62
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --id <claim_id> | text | — | New Claim id. Omit to derive one from --kind and --label (thesis_irr_clears_the_bar); the answer names it. |
| --kind <kind> | thesis \| risk \| catalyst \| counter \| question \| market_consensus | 必填 | What the claim is: thesis (what you conclude), risk (what could break it, needs --probability AND --severity), catalyst (what would move it, needs --probability), counter (the case against), question (open), market_consensus (someone else's view, needs --attribution). Give the required ones on this write, e.g. --kind risk --probability 0.3 --severity high. See `deepcell ref claim` and `deepcell guide revise/reasoning`. |
| --label <label> | text | — | <Label> text. The finding itself, not the subject it concerns — "Working capital is a source of cash", not "Working capital". Renders as the reasoning outline row, and a Deck may bind it as a slide headline. |
| --label-file <label_file> | file | — | File holding the <Label> text; '-' reads stdin. Prefer this over --label for text containing '$' — inline shell arguments mangle dollar amounts. |
| --body <body> | text | — | <Body> text. |
| --body-file <body_file> | file | — | File holding the <Body> text; '-' reads stdin. Prefer this over --body for text containing '$' — inline shell arguments mangle dollar amounts. |
| --body-notation <body_notation> | markdown \| text | — | What the <Body> IS: markdown or literal text. Omitted keeps what the body declares; a body that declares nothing is read as markdown when it carries a markdown mark (a [[deepcell:...]] reference, **bold**, a heading) and lints as notation_inferred until it is declared. |
| --status-ref <status_ref> | text | — | Model Status dimension id (e.g. actual / projected) — NOT the claim lifecycle state (that is --status). |
| --calc-ref <calc_ref> | text | — | ONE CalcDef id anchoring this claim to the formula it rests on (never a list). |
| --sensitivity-ref <sensitivity_ref> | text | — | blockId of the sensitivity grid this claim was read off (blockType="sensitivity"). A range in a risk or catalyst claim names the grid it came from; the write refuses an id no such block carries. |
| --item-refs <item_refs> | text | — | Item ids anchoring this claim to a Spreadsheet — or @order values and lo-hi ranges, the itemOrders grammar (positional: an inserted row moves them; name the ids for a fixed anchor). When Items exist, thesis/risk/catalyst claims need --item-refs or --calc-ref, else unanchored_claim warns (they become invisible to reasoning-diff and item-scoped queries). A qualitative no-grid file does not invent Items; question/market_consensus are always exempt. |
| --probability <probability> | float | — | Likelihood, 0-1 (required for kind=risk / catalyst). |
| --severity <severity> | low \| med \| high | — | Qualitative impact (required for kind=risk). |
| --confidence <confidence> | float | — | How strongly you hold this claim, 0-1. |
| --strength <strength> | low \| med \| high | — | How strongly the claim is held, qualitatively. Independent of --confidence (the numeric form); a claim may carry both. |
| --parent-claim-ref <parent_claim_ref> | text | — | Claim id this one hangs under (hierarchy, not an Argument edge). |
| --attribution <attribution> | text | — | Who holds this view (required for kind=market_consensus), e.g. 'Bloomberg consensus, 2026-07'. |
| --origin <origin> | anticipated \| asked | — | kind=question only — where the question came from: anticipated (prepared before a review: what a supervisor or client will likely ask) or asked (actually raised, e.g. a chat follow-up). Leave it off the key question and the analysis's own sub-questions. Record the answer with `add-argument --from-id <answer> --rel answers --to-id <question>`. |
| --audience <audience> | text | — | kind=question only — who asks it, free text ("IC", "client CFO"). |
| --status <status> | draft \| active \| superseded \| falsified \| revoked | — | Claim lifecycle state — NOT the model's Status dimension (that is --status-ref). |
| --context-refs <context_refs> | text | — | Comma-separated context (period) ids this node reasons across; 'A..B' is a range, every period from A to B inclusive in context order (e.g. 'FY2027E..FY2031E'). 'A,B' stays two periods. |
| --scenario-ref <scenario_ref> | text | — | Scenario id this node is about, when it holds only in one world. |
| --custom-dimensions <custom_dimensions> | text | — | Custom dimension members as `dim:member;dim2:member2` — the fifth axis of the anchor (e.g. `region:emea`). |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed · 1 — written-but-invalid

#### reasoning add-evidence

Add a new <Evidence> to FILENAME's <Reasoning> section.

deepcell reasoning add-evidence <filename> --id <evidence_id> --source-ref <source_ref>
```bash
deepcell reasoning add-evidence model.deepcell --id e_10k --source-ref src_aapl_10k_fy25 --excerpt 'Gross margin of 46.2%' --retrieved-at 2026-02-19T10:30:00Z
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --id <evidence_id> | text | 必填 | New Evidence id. |
| --source-ref <source_ref> | text | 必填 | sourceId of a <Source> in <SourceDefinitions>. |
| --label <label> | text | — | <Label> text. What the source says, in one line of your own — "FY2028 revenue growth guided to ~70%", not the quotation. Names the row in the reasoning outline's Data and sources list; the excerpt is what the source SAID and is reproduced verbatim under it. |
| --label-file <label_file> | file | — | File holding the <Label> text; '-' reads stdin. Prefer this over --label for text containing '$' — inline shell arguments mangle dollar amounts. |
| --excerpt <excerpt> | text | — | <Excerpt> text: the source's own words, verbatim. |
| --excerpt-file <excerpt_file> | file | — | File holding the <Excerpt> text; '-' reads stdin. Prefer this over --excerpt for text containing '$' — inline shell arguments mangle dollar amounts. |
| --at <at> | text | — | Position in the source: page:47 \| t:00:14:32 \| text:HEADING[,NEXT] — HEADING copied verbatim from the page (it becomes a #:~:text= jump), NEXT the text right after it. |
| --reliability <reliability> | text | — | primary \| secondary \| tertiary. |
| --effective-date <effective_date> | text | — | ISO 8601 date the evidence is as of, or a date-time with its offset (2026-03-14T09:30:00+08:00); stored as written, never converted. |
| --retrieved-at <retrieved_at> | text | — | ISO8601 date. |
| --item-refs <item_refs> | text | — | Item ids this evidence bears on (or @order values / lo-hi ranges). Anchoring it here is what lets `reasoning impact` reach the evidence when one of those items moves; `update-evidence` can retrofit it later. |
| --status-ref <status_ref> | text | — | Model Status dimension id (e.g. actual / projected) the evidence speaks to. |
| --context-refs <context_refs> | text | — | Comma-separated context (period) ids this node reasons across; 'A..B' is a range, every period from A to B inclusive in context order (e.g. 'FY2027E..FY2031E'). 'A,B' stays two periods. |
| --scenario-ref <scenario_ref> | text | — | Scenario id this node is about, when it holds only in one world. |
| --custom-dimensions <custom_dimensions> | text | — | Custom dimension members as `dim:member;dim2:member2` — the fifth axis of the anchor (e.g. `region:emea`). |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed · 1 — written-but-invalid

#### reasoning apply

Apply a batch of reasoning ops atomically.

deepcell reasoning apply <filename>
```bash
deepcell reasoning apply model.deepcell
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --ops-file <ops_file> | file | — | JSON file with an `ops` array (use '-' for stdin). |
| --ops <ops_inline> | text | — | Inline ops JSON (same shapes as --ops-file). |
| --dry-run | boolean | — | Validate the batch and print its findings; write nothing. A real apply refuses a bad batch whole too, so this is for reading the findings before committing, not for safety. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed

#### reasoning delete-argument

Delete one <Argument> edge from FILENAME's <Reasoning> section.

deepcell reasoning delete-argument <filename> [argument_id]
```bash
deepcell reasoning delete-argument model.deepcell --from-id r_pricing --edge-rel refutes --to-id t_gm
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| argument_id | text | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --from-id <from_id> | text | — | Address: the edge's @from. |
| --edge-rel <edge_rel> | supports \| refutes \| depends_on \| derives_from \| variant_of \| supersedes \| contradicts \| references \| answers \| asks_about | — | Address: the edge's @rel. |
| --to-id <to_id> | text | — | Address: the edge's @to. |
| --cascade | boolean | — | Also remove every Argument touching the node (default). --no-cascade keeps them, and is refused with code=would_dangle unless you also pass --allow-dangling — a dangling edge lints, and is still addressable by its (from, rel, to) or its id, so it can be cleaned up later. |
| --allow-dangling | boolean | — | With --no-cascade, permit the delete even though it orphans Arguments. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed · 1 — written-but-invalid

#### reasoning delete-assumption

Delete the <Assumption> NODE_ID from FILENAME's <Reasoning> section.

deepcell reasoning delete-assumption <filename> <node_id>
```bash
deepcell reasoning delete-assumption model.deepcell <node_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| node_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --cascade | boolean | — | Also remove every Argument touching the node (default). --no-cascade keeps them, and is refused with code=would_dangle unless you also pass --allow-dangling — a dangling edge lints, and is still addressable by its (from, rel, to) or its id, so it can be cleaned up later. |
| --allow-dangling | boolean | — | With --no-cascade, permit the delete even though it orphans Arguments. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed · 1 — written-but-invalid

#### reasoning delete-claim

Delete the <Claim> NODE_ID from FILENAME's <Reasoning> section.

deepcell reasoning delete-claim <filename> <node_id>
```bash
deepcell reasoning delete-claim model.deepcell t_gm --cascade
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| node_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --cascade | boolean | — | Also remove every Argument touching the node (default). --no-cascade keeps them, and is refused with code=would_dangle unless you also pass --allow-dangling — a dangling edge lints, and is still addressable by its (from, rel, to) or its id, so it can be cleaned up later. |
| --allow-dangling | boolean | — | With --no-cascade, permit the delete even though it orphans Arguments. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed · 1 — written-but-invalid

#### reasoning delete-evidence

Delete the <Evidence> NODE_ID from FILENAME's <Reasoning> section.

deepcell reasoning delete-evidence <filename> <node_id>
```bash
deepcell reasoning delete-evidence model.deepcell <node_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| node_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --cascade | boolean | — | Also remove every Argument touching the node (default). --no-cascade keeps them, and is refused with code=would_dangle unless you also pass --allow-dangling — a dangling edge lints, and is still addressable by its (from, rel, to) or its id, so it can be cleaned up later. |
| --allow-dangling | boolean | — | With --no-cascade, permit the delete even though it orphans Arguments. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed · 1 — written-but-invalid

#### reasoning graph

Render the Argument graph from FILENAME as Mermaid (default) or DOT.

deepcell reasoning graph <filename>
```bash
deepcell reasoning graph model.deepcell --syntax mermaid
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --syntax <graph_syntax> | mermaid \| dot | mermaid | Graph syntax to emit. Use the global -f json for the raw graph payload. |

退出码： 0 — completed

#### reasoning impact

Walk Argument edges from CLAIM_ID and list downstream nodes affected if it's falsified.

deepcell reasoning impact <filename> <claim_id>
```bash
deepcell reasoning impact model.deepcell a_hiring
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| claim_id | text | 必填 |

退出码： 0 — completed

#### reasoning lint

Lint the <Reasoning> section of FILENAME for structural issues.

deepcell reasoning lint <filename>
```bash
deepcell reasoning lint model.deepcell --strict
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --strict | boolean | — | Exit non-zero on warn-level findings too (default: only error-level findings fail). |

退出码： 0 — completed · 1 — read-only-check

#### reasoning set-conclusion

Declare which Claim is FILENAME's main conclusion.

deepcell reasoning set-conclusion <filename> [claim_id]
```bash
deepcell reasoning set-conclusion model.deepcell t_gm
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| claim_id | text | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --clear | boolean | — | Remove the declaration and fall back to deriving the apex from the argument topology. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed · 1 — written-but-invalid

#### reasoning set-key-question

Declare which question FILENAME exists to answer.

deepcell reasoning set-key-question <filename> [claim_id]
```bash
deepcell reasoning set-key-question model.deepcell
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| claim_id | text | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --clear | boolean | — | Remove the declaration. The header then falls back to the `answers` edge off the conclusion, then to the document's only question, and otherwise shows nothing. |
| --needs-review | boolean | — | Mark the question as inferred rather than stated, so it renders as provisional until someone confirms it. Declaring without this flag clears it. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed

#### reasoning supersede-assumption

Replace ASSUMPTION_ID with a new Assumption, keeping the old as history.

deepcell reasoning supersede-assumption <filename> <assumption_id> --id <new_id>
```bash
deepcell reasoning supersede-assumption model.deepcell a_hiring --id a_hiring_v2 --label 'Hiring lands one quarter late'
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| assumption_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --id <new_id> | text | 必填 | Id of the replacement Assumption. |
| --label <label> | text | — | <Label> text of the replacement. The finding itself, not the subject it concerns — "Working capital is a source of cash", not "Working capital". Renders as the reasoning outline row, and a Deck may bind it as a slide headline. |
| --label-file <label_file> | file | — | File holding the replacement <Label> text; '-' reads stdin. Prefer this over --label for text containing '$' — inline shell arguments mangle dollar amounts. |
| --body <body> | text | — | <Body> text of the replacement. |
| --body-file <body_file> | file | — | File holding the replacement <Body> text; '-' reads stdin. Prefer this over --body for text containing '$' — inline shell arguments mangle dollar amounts. |
| --body-notation <body_notation> | markdown \| text | — | What the <Body> IS: markdown or literal text. Omitted keeps what the body declares; a body that declares nothing is read as markdown when it carries a markdown mark (a [[deepcell:...]] reference, **bold**, a heading) and lints as notation_inferred until it is declared. |
| --item-refs <item_refs> | text | — | Item ids, @order values or lo-hi order ranges (the itemOrders grammar). |
| --status-ref <status_ref> | text | — | Model Status dimension id. |
| --calc-ref <calc_ref> | text | — | CalcDef id this assumption drives. |
| --confidence <confidence> | float | — | Confidence in the replacement, 0-1. |
| --status <status> | holding \| uncertain \| broken \| superseded | — | Lifecycle status of the replacement. |
| --verified-at <verified_at> | text | — | ISO date (YYYY-MM-DD) this assumption was last confirmed to still hold (@verifiedAt). Records WHEN it was checked; --status holding records that it stands. |
| --broken-at <broken_at> | text | — | ISO date (YYYY-MM-DD) this assumption was found no longer to hold (@brokenAt). Records WHEN it failed; --status broken records THAT it failed — set both when actuals contradict an assumption. |
| --context-refs <context_refs> | text | — | Comma-separated context (period) ids this node reasons across; 'A..B' is a range, every period from A to B inclusive in context order (e.g. 'FY2027E..FY2031E'). 'A,B' stays two periods. |
| --scenario-ref <scenario_ref> | text | — | Scenario id this node is about, when it holds only in one world. |
| --custom-dimensions <custom_dimensions> | text | — | Custom dimension members as `dim:member;dim2:member2` — the fifth axis of the anchor (e.g. `region:emea`). |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed · 1 — written-but-invalid

#### reasoning supersede-claim

Replace CLAIM_ID with a new Claim, keeping the old one as history.

deepcell reasoning supersede-claim <filename> <claim_id> --id <new_id>
```bash
deepcell reasoning supersede-claim model.deepcell t_gm --id t_gm_v2 --label 'Gross margin expands, slower' --body 'Mix shift lifts GM 120bps.' --confidence 0.55
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| claim_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --id <new_id> | text | 必填 | Id of the replacement Claim. |
| --label <label> | text | — | <Label> text of the replacement. The finding itself, not the subject it concerns — "Working capital is a source of cash", not "Working capital". Renders as the reasoning outline row, and a Deck may bind it as a slide headline. |
| --label-file <label_file> | file | — | File holding the replacement <Label> text; '-' reads stdin. Prefer this over --label for text containing '$' — inline shell arguments mangle dollar amounts. |
| --body <body> | text | — | <Body> text of the replacement. |
| --body-file <body_file> | file | — | File holding the replacement <Body> text; '-' reads stdin. Prefer this over --body for text containing '$' — inline shell arguments mangle dollar amounts. |
| --body-notation <body_notation> | markdown \| text | — | What the <Body> IS: markdown or literal text. Omitted keeps what the body declares; a body that declares nothing is read as markdown when it carries a markdown mark (a [[deepcell:...]] reference, **bold**, a heading) and lints as notation_inferred until it is declared. |
| --kind <kind> | thesis \| risk \| catalyst \| counter \| question \| market_consensus | — | Kind of the replacement (defaults to the superseded claim's kind). |
| --item-refs <item_refs> | text | — | Item ids, @order values or lo-hi order ranges (the itemOrders grammar). |
| --context-refs <context_refs> | text | — | Comma-separated context ids; 'A..B' is a range in context order. |
| --status-ref <status_ref> | text | — | Model Status dimension id. |
| --calc-ref <calc_ref> | text | — | CalcDef id this claim is anchored to. |
| --confidence <confidence> | float | — | Confidence in the replacement, 0-1. |
| --strength <strength> | low \| med \| high | — | How strongly the replacement is held, qualitatively. Not inherited from the superseded claim: a reassessment that reused the old strength would publish a judgement nobody made. |
| --probability <probability> | float | — | Likelihood of the replacement, 0-1. Not inherited: required when the replacement is a risk or catalyst. |
| --severity <severity> | low \| med \| high | — | Qualitative impact of the replacement. Not inherited: required when the replacement is a risk. |
| --attribution <attribution> | text | — | Who holds the replacement view. Not inherited: required when the replacement is a market_consensus. |
| --scenario-ref <scenario_ref> | text | — | Scenario id this node is about, when it holds only in one world. |
| --custom-dimensions <custom_dimensions> | text | — | Custom dimension members as `dim:member;dim2:member2` — the fifth axis of the anchor (e.g. `region:emea`). |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed · 1 — written-but-invalid

#### reasoning update-argument

Patch an <Argument> edge; only the attributes you pass are changed.

deepcell reasoning update-argument <filename> [argument_id]
```bash
deepcell reasoning update-argument model.deepcell arg_pricing --weight 0.6
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| argument_id | text | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --from-id <from_id> | text | — | Address: the edge's @from. |
| --edge-rel <edge_rel> | supports \| refutes \| depends_on \| derives_from \| variant_of \| supersedes \| contradicts \| references \| answers \| asks_about | — | Address: the @rel the edge has now. --rel is what to change it to. |
| --to-id <to_id> | text | — | Address: the edge's @to. |
| --rel <rel> | supports \| refutes \| depends_on \| derives_from \| variant_of \| supersedes \| contradicts \| references \| answers \| asks_about | — | Reclassify the edge — see `deepcell reasoning add-argument --help`. |
| --weight <weight> | float | — | How much this edge carries, 0-1. |
| --body <body> | text | — | Replacement <Body> text. |
| --body-file <body_file> | file | — | File holding the replacement <Body> text; '-' reads stdin. Prefer this over --body for text containing '$' — inline shell arguments mangle dollar amounts. |
| --body-notation <body_notation> | markdown \| text | — | What the <Body> IS: markdown or literal text. Omitted keeps what the body declares; a body that declares nothing is read as markdown when it carries a markdown mark (a [[deepcell:...]] reference, **bold**, a heading) and lints as notation_inferred until it is declared. |
| --status <status> | text | — | Argument lifecycle status (active / superseded / revoked). |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed · 1 — written-but-invalid

#### reasoning update-assumption

Update attributes on an existing <Assumption> ASSUMPTION_ID.

deepcell reasoning update-assumption <filename> <assumption_id>
```bash
deepcell reasoning update-assumption model.deepcell a_hiring --status broken --broken-at 2026-07-31
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| assumption_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --label <label> | text | — | Replacement <Label> text. The finding itself, not the subject it concerns — "Working capital is a source of cash", not "Working capital". Renders as the reasoning outline row, and a Deck may bind it as a slide headline. |
| --label-file <label_file> | file | — | File holding the replacement <Label> text; '-' reads stdin. Prefer this over --label for text containing '$' — inline shell arguments mangle dollar amounts. |
| --body <body> | text | — | Replacement <Body> text. |
| --body-file <body_file> | file | — | File holding the replacement <Body> text; '-' reads stdin. Prefer this over --body for text containing '$' — inline shell arguments mangle dollar amounts. |
| --body-notation <body_notation> | markdown \| text | — | What the <Body> IS: markdown or literal text. Omitted keeps what the body declares; a body that declares nothing is read as markdown when it carries a markdown mark (a [[deepcell:...]] reference, **bold**, a heading) and lints as notation_inferred until it is declared. |
| --status-ref <status_ref> | text | — | Model Status dimension id (e.g. actual / projected) — NOT the assumption's lifecycle state (that is --status). |
| --calc-ref <calc_ref> | text | — | ONE CalcDef id anchoring this assumption to a formula (never a list). |
| --item-refs <item_refs> | text | — | Item ids the assumption constrains (or @order values / lo-hi ranges) — the fix for unanchored_assumption when the file has Items. |
| --confidence <confidence> | float | — | How strongly you hold this assumption, 0-1. |
| --status <status> | holding \| uncertain \| broken \| superseded | — | Assumption lifecycle state: holding until something contradicts it, broken once actuals do, superseded when a newer assumption replaces it. |
| --verified-at <verified_at> | text | — | ISO date (YYYY-MM-DD) this assumption was last confirmed to still hold (@verifiedAt). Records WHEN it was checked; --status holding records that it stands. |
| --broken-at <broken_at> | text | — | ISO date (YYYY-MM-DD) this assumption was found no longer to hold (@brokenAt). Records WHEN it failed; --status broken records THAT it failed — set both when actuals contradict an assumption. |
| --context-refs <context_refs> | text | — | Comma-separated context (period) ids this node reasons across; 'A..B' is a range, every period from A to B inclusive in context order (e.g. 'FY2027E..FY2031E'). 'A,B' stays two periods. |
| --scenario-ref <scenario_ref> | text | — | Scenario id this node is about, when it holds only in one world. |
| --custom-dimensions <custom_dimensions> | text | — | Custom dimension members as `dim:member;dim2:member2` — the fifth axis of the anchor (e.g. `region:emea`). |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed · 1 — written-but-invalid

#### reasoning update-claim

Update attributes on an existing <Claim> CLAIM_ID in FILENAME.

deepcell reasoning update-claim <filename> <claim_id>
```bash
deepcell reasoning update-claim model.deepcell t_gm --status falsified
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| claim_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --kind <kind> | thesis \| risk \| catalyst \| counter \| question \| market_consensus | — | Reclassify the claim — see `deepcell reasoning add-claim --help` for what each kind means. |
| --label <label> | text | — | Replacement <Label> text. The finding itself, not the subject it concerns — "Working capital is a source of cash", not "Working capital". Renders as the reasoning outline row, and a Deck may bind it as a slide headline. |
| --label-file <label_file> | file | — | File holding the replacement <Label> text; '-' reads stdin. Prefer this over --label for text containing '$' — inline shell arguments mangle dollar amounts. |
| --body <body> | text | — | Replacement <Body> text. |
| --body-file <body_file> | file | — | File holding the replacement <Body> text; '-' reads stdin. Prefer this over --body for text containing '$' — inline shell arguments mangle dollar amounts. |
| --body-notation <body_notation> | markdown \| text | — | What the <Body> IS: markdown or literal text. Omitted keeps what the body declares; a body that declares nothing is read as markdown when it carries a markdown mark (a [[deepcell:...]] reference, **bold**, a heading) and lints as notation_inferred until it is declared. |
| --status-ref <status_ref> | text | — | Model Status dimension id (e.g. actual / projected) — NOT the claim lifecycle state (that is --status). |
| --calc-ref <calc_ref> | text | — | ONE CalcDef id anchoring this claim to the formula it rests on (never a list). |
| --sensitivity-ref <sensitivity_ref> | text | — | blockId of the sensitivity grid this claim was read off (blockType="sensitivity"). A range in a risk or catalyst claim names the grid it came from; the write refuses an id no such block carries. |
| --item-refs <item_refs> | text | — | Item ids anchoring this claim to a Spreadsheet (or @order values / lo-hi ranges) — the fix for unanchored_claim when the file has Items. |
| --probability <probability> | float | — | Likelihood, 0-1 (required for kind=risk / catalyst). |
| --severity <severity> | low \| med \| high | — | Qualitative impact (required for kind=risk). |
| --confidence <confidence> | float | — | How strongly you hold this claim, 0-1. |
| --strength <strength> | low \| med \| high | — | How strongly the claim is held, qualitatively. Independent of --confidence (the numeric form); a claim may carry both. |
| --parent-claim-ref <parent_claim_ref> | text | — | Claim id this one hangs under (hierarchy, not an Argument edge). |
| --attribution <attribution> | text | — | Who holds this view (required for kind=market_consensus). |
| --origin <origin> | anticipated \| asked \|  | — | kind=question only — where the question came from: anticipated (prepared before a review: what a supervisor or client will likely ask) or asked (actually raised, e.g. a chat follow-up). Leave it off the key question and the analysis's own sub-questions. Record the answer with `add-argument --from-id <answer> --rel answers --to-id <question>`. Pass '' to clear it. |
| --audience <audience> | text | — | kind=question only — who asks it, free text ("IC", "client CFO"). Pass '' to clear it. |
| --status <status> | draft \| active \| superseded \| falsified \| revoked | — | Claim lifecycle state — NOT the model's Status dimension (that is --status-ref). |
| --context-refs <context_refs> | text | — | Comma-separated context (period) ids this node reasons across; 'A..B' is a range, every period from A to B inclusive in context order (e.g. 'FY2027E..FY2031E'). 'A,B' stays two periods. |
| --scenario-ref <scenario_ref> | text | — | Scenario id this node is about, when it holds only in one world. |
| --custom-dimensions <custom_dimensions> | text | — | Custom dimension members as `dim:member;dim2:member2` — the fifth axis of the anchor (e.g. `region:emea`). |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed · 1 — written-but-invalid

#### reasoning update-evidence

Patch an <Evidence> node; only the attributes you pass are changed.

deepcell reasoning update-evidence <filename> <evidence_id>
```bash
deepcell reasoning update-evidence model.deepcell <evidence_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| evidence_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --label <label> | text | — | Replacement <Label> text. What the source says, in one line of your own — "FY2028 revenue growth guided to ~70%", not the quotation. Names the row in the reasoning outline's Data and sources list; the excerpt is what the source SAID and is reproduced verbatim under it. |
| --label-file <label_file> | file | — | File holding the replacement <Label> text; '-' reads stdin. Prefer this over --label for text containing '$' — inline shell arguments mangle dollar amounts. |
| --excerpt <excerpt> | text | — | Replacement <Excerpt> text: the source's own words, verbatim. (--body is an alias: an <Evidence> has no <Body>.) |
| --excerpt-file <excerpt_file> | file | — | File holding the replacement <Excerpt> text; '-' reads stdin. Prefer this over --excerpt for text containing '$' — inline shell arguments mangle dollar amounts. |
| --source-ref <source_ref> | text | — | Replacement @sourceRef: the sourceId of a <Source> in <SourceDefinitions>. |
| --url <url> | text | — | Refused: an <Evidence> carries no URL. The URL is the <Source>'s locator — `deepcell defs update-source FILE --id <sourceId> --locator URL`. |
| --effective-date <effective_date> | text | — | Replacement @effectiveDate (ISO date, or date-time with its offset; stored as written). |
| --item-refs <item_refs> | text | — | Item ids, @order values or lo-hi order ranges (the itemOrders grammar). |
| --context-refs <context_refs> | text | — | Comma-separated context ids; 'A..B' is a range in context order. |
| --status-ref <status_ref> | text | — | Model Status dimension id (e.g. actual / projected) the evidence speaks to. |
| --scenario-ref <scenario_ref> | text | — | Scenario id this node is about, when it holds only in one world. |
| --custom-dimensions <custom_dimensions> | text | — | Custom dimension members as `dim:member;dim2:member2` — the fifth axis of the anchor (e.g. `region:emea`). |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed · 1 — written-but-invalid

#### write

Create a file, or replace an existing one wholesale.

deepcell write <filename>
```bash
deepcell write model.deepcell --file ./model.deepcell
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --stdin | boolean | — | Read content from stdin. |
| --file <from_file> | path | — | Read content from a local file. |
| --content <from_content> | text | — | Pass file content inline (useful for MCP/programmatic access). |
| --content-base64 <from_b64> | text | — | Pass file content as a base64-encoded string. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking — the `Revision:` line `deepcell cat` prints on stderr (the `revision` field under `-f json`). The write is refused with a conflict if FILENAME changed since (a change to a different file is not a conflict). |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed · 1 — written-but-invalid

### revise — change a premise and reassess what depends on it

#### changes diff

Show what one change did, semantically.

deepcell changes diff <base_revision> [head_revision]
```bash
deepcell changes diff <base_revision>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| base_revision | revision | 必填 |
| head_revision | revision | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --file <filename> | text | — | Filter diff by filename. |

退出码： 0 — completed

#### changes list

List document changes, newest first.

deepcell changes list [filename_pos]
```bash
deepcell changes list
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename_pos | text | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --file <filename> | text | — | Filter by filename. |
| --limit <limit> | integer range | 20 | Number of changes to show (1-200). |
| --since <since_revision> | revision | — | Only changes that moved the branch forward from this revision. |
| --by-commit | boolean | — | Show each commit of a grouped change on its own line, with the <parent> <sha> range that undoes just that commit. |

退出码： 0 — completed

#### changes revert

Undo one change by committing its inverse onto the current tip.

deepcell changes revert <base_revision> [head_revision]
```bash
deepcell changes revert 1a2b3c4d..5e6f7a8b
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| base_revision | revision | 必填 |
| head_revision | revision | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --yes | boolean | — | Skip confirmation prompt. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed

#### commit

Commit changes staged in the project by something other than you.

```bash
deepcell commit
```

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --message <message> | text | — | Commit message. |

退出码： 0 — completed · 1 — written-but-invalid

#### diff

Show diff between two revisions (like git diff).

deepcell diff <revision_a> [revision_b]
```bash
deepcell diff <revision_a>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| revision_a | text | 必填 |
| revision_b | text | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --file <filename> | text | — | Filter diff by filename. |

退出码： 0 — completed

#### log

Show version history for the project (like git log).

deepcell log [filename_pos]
```bash
deepcell log
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename_pos | text | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --file <filename> | text | — | Filter by filename. |
| --limit <limit> | integer range | 20 | Number of entries to show. |
| --after <after_sha> | text | — | Pagination cursor: start AFTER this commit sha. Pass the last sha of the previous page to read the next one. |

退出码： 0 — completed

#### replace

Replace raw XML text in a file — the last-resort editor.

deepcell replace <filename> [old_string] [new_string]
```bash
deepcell replace model.deepcell "<Old>text</Old>" "<New>text</New>"
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| old_string | text | 可选 |
| new_string | text | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --replace-all | boolean | — | Replace every occurrence instead of requiring a unique match. |
| --batch <batch_file> | text | — | Replacement as a JSON object {"old_string": "...", "new_string": "..."} — a file path, '-' for stdin, or inline JSON. Use this for multiline XML. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed · 1 — written-but-invalid

#### restore

Restore the project to a previous revision (like git checkout).

```bash
deepcell restore <revision>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| revision | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --file <filename> | text | — | Restore specific file only. |
| --yes | boolean | — | Skip confirmation prompt. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed

#### rm

Delete a file from the project.

deepcell rm <filename>
```bash
deepcell rm model.deepcell
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --yes | boolean | — | Skip confirmation prompt. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed

#### variant checkout

Check out a variant branch for local edits.

deepcell variant checkout [name]
```bash
deepcell variant checkout
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| name | text | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --main | boolean | — | Switch back to the main branch (clear active variant). |

退出码： 0 — completed

#### variant create

Create a new variant branch.

```bash
deepcell variant create <name>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| name | text | 必填 |

退出码： 0 — completed

#### variant diff

Show diff between a variant branch and main.

deepcell variant diff [name]
```bash
deepcell variant diff
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| name | text | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --file <file_path> | text | — | Limit the diff to a single file. |

退出码： 0 — completed

#### variant list

List variants in the workspace.

```bash
deepcell variant list
```

退出码： 0 — completed

#### variant merge

Merge a variant branch back into main.

deepcell variant merge [name]
```bash
deepcell variant merge
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| name | text | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --resolve <resolve> | ours \| theirs | — | Conflict resolution strategy: 'ours' keeps main, 'theirs' keeps variant. |

退出码： 0 — completed · 1 — conflict

### verify — change one thing, see everything it affects

#### assumption impact

List Claims that depend_on ASSUMPTION_ID.

deepcell assumption impact <filename> <assumption_id>
```bash
deepcell assumption impact model.deepcell a_hiring
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| assumption_id | text | 必填 |

退出码： 0 — completed · 2 — unparseable-document

#### claim falsified

List every Claim in FILENAME whose status is `falsified`.

deepcell claim falsified <filename>
```bash
deepcell claim falsified model.deepcell
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

退出码： 0 — completed · 2 — unparseable-document

#### claim history

Walk the supersedes chain backwards from CLAIM_ID (newest first).

deepcell claim history <filename> <claim_id>
```bash
deepcell claim history model.deepcell <claim_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| claim_id | text | 必填 |

退出码： 0 — completed · 2 — unparseable-document

#### claim variant

Show your view of CLAIM_ID beside the consensus it is a variant of.

deepcell claim variant <filename> <claim_id>
```bash
deepcell claim variant model.deepcell <claim_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| claim_id | text | 必填 |

退出码： 0 — completed · 2 — unparseable-document

#### impact apply

Apply one reviewed fix, and record it as `revised`.

deepcell impact apply <filename> <item_key> --surface <surface> --locator <locator> --op <op> --target-id <target_id>
```bash
deepcell impact apply model.deepcell <item_key> --surface <surface> --locator <locator> --op <op> --target-id <target_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| item_key | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --surface <surface> | text | 必填 | The surface the item is on. |
| --locator <locator> | text | 必填 | The item's address. |
| --op <op> | text | 必填 | The reasoning op to apply: add_claim, add_assumption, add_argument, update_claim, update_assumption, supersede_claim or supersede_assumption. |
| --target-id <target_id> | text | 必填 | The Claim or Assumption it addresses. |
| --payload <payload> | text | — | The op's fields, as JSON: attribute names plus label_text / body_text, the keys `deepcell ref op/<op>` lists. Omit for an op that needs none. |
| --new-claim <new_claim> | text | — | JSON for the replacement Claim, same keys as --payload (id required). Required by supersede_claim. |
| --new-assumption <new_assumption> | text | — | JSON for the replacement Assumption, same keys as --payload (id required). Required by supersede_assumption. |
| --expected-revision <expected_revision> | text | — | The revision you read at. A newer document is a 409 rather than an overwrite. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed

#### impact reopen

Undo one review decision.

deepcell impact reopen <filename> <item_key>
```bash
deepcell impact reopen model.deepcell <item_key>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| item_key | text | 必填 |

退出码： 0 — completed

#### impact review

Mark items reviewed — their markers disappear.

deepcell impact review <filename> [item_keys...]
```bash
deepcell impact review model.deepcell
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |
| item_keys... | text | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --since <since> | text | — | Review the items `impact show --since` lists from this revision (a SHA or HEAD~N): all of them, or only the ITEM_KEYs named. Each key's surface and locator are looked up, so neither flag is needed. |
| --surface <surface> | text | — | The surface the item is on, as `impact show` prints it (one key, without --since). |
| --locator <locator> | text | — | The item's address — the `locator` line `impact show` prints (one key, without --since). |
| --outcome <outcome> | confirmed \| revised | confirmed | confirmed (default): it still reads correctly. revised: it was rewritten. |
| --kind <kind> | text | — | The item's kind. An unresolved one is refused: it needs a rebind. |
| --rationale <rationale> | text | — | Why this edit was made. Becomes the commit message body, so the history reads as the decision rather than the coordinates the diff already shows. `-m` and `--message` are aliases of `--rationale`. |
| --title <title> | text | — | Short commit subject (e.g. 'Q3 actuals update'). Combined with --rationale as 'title: rationale'. The mechanical summary the server would have written is kept as a Summary trailer either way. |

退出码： 0 — completed

#### impact show

List every place that may need review after a change.

deepcell impact show <filename> --since <base_revision>
```bash
deepcell impact show model.deepcell --since <base_revision>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --since <base_revision> | text | 必填 | The revision to compare from: a SHA from `deepcell log`, or HEAD~N for the N-th commit before the workspace's newest (resolved through the log here; the server takes a 7-64 character SHA only). Note the SHA before you edit — a premise change is usually several commits, and HEAD~1 reaches only the last of them. |
| --revision <revision> | text | — | The revision to compare to (a SHA or HEAD~N). Defaults to the working tree. |
| --threshold <threshold> | float | — | Relative move at or above which a value change is material. Defaults to the built-in 1%. |
| --include-reviewed | boolean | — | Ignore review decisions: list every item as derived, reviewed or not. Nothing marks which were reviewed (the `reviewed` count reads 0); compare with the listing without this flag. |

退出码： 0 — completed

#### lint

List a document's lint findings, errors first — nothing else.

deepcell lint <filename>
```bash
deepcell lint model.deepcell --building
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --building | boolean | — | The document is still being built: a declared surface with nothing on it yet (surface_missing) is a warning, not a gating error. Drop it for the hand-off lint. |
| --since <since_revision> | text | — | Mark each finding pre-existing or new against this revision: `HEAD~1` for the commit before yours, or a SHA from `deepcell log`. |
| --measure | boolean | — | Measure every deck slide that has no fit measurement yet before reporting (one browser pass per slide in the export service). |
| --fail-on <fail_on> | any \| introduced | any | With --since: `any` exits 1 on every error-level finding; `introduced` only on those the baseline did not have. |
| --rule <rule_codes> | text | — | Only the findings with these codes (`unrendered_value,check_row_nonzero`). The exit code then counts only them. |
| --summary | boolean | — | One line per code — its count and severity — instead of every finding. |
| --workspace <workspace_slug> | text | — | Override active workspace. |

退出码： 0 — completed · 1 — read-only-check

#### reasoning-diff

Warn when an edit moved something a Claim was anchored to.

deepcell reasoning-diff <file>
```bash
deepcell reasoning-diff model.deepcell
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| file | path | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --accept | boolean | — | Print warnings but exit 0 (acknowledge and continue). |
| --since-branch-base <since_branch_base> | path | — | Path to a third .deepcell file representing the branch base. When supplied, drift is computed across both branch_base->HEAD and HEAD->working intervals so accumulated commits surface. |

退出码： 0 — completed · 1 — read-only-check · 2 — unparseable-document

#### relationships

Show what is wired to what in a .deepcell file.

deepcell relationships <filename>
```bash
deepcell relationships model.deepcell --type business
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --type <graph_type> | items \| dependencies \| blocks \| business \| unified | dependencies | Graph type (default dependencies): dependencies = what each formula reads; items = the Item hierarchy; blocks = sheets, blocks and the items each shows; business = the Item-centric Relationships workspace, with values and the reasoning nodes anchored to each item; unified = all of it plus the claims citing each item and the argument. |
| --item <item> | text | — | Answer for one item (plain output): what its formula reads, what reads it, and every other edge naming it. |
| --depth <depth> | integer range | — | With --item: formula steps to walk each way (default 1). |
| --offset <offset> | integer range | — | The first line of the page (plain output). A page that leaves lines out ends with the command for the next one. |
| --limit <limit> | integer range | — | Lines per page (plain output; default 200). |

退出码： 0 — completed

### present — deliver the work to someone else

#### share create

Create a share link for FILENAME and print its viewer URL.

deepcell share create <filename>
```bash
deepcell share create model.deepcell --permission view
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --permission <permission> | view \| edit | view | Access level for the link. Edit links require an account. |
| --expires-days <expires_days> | integer range | — | Days until the link expires. Every link expires; omit this to take the default (90 days, or 7 for a password-less --permission edit link; 7 from an anonymous session). Larger values are clamped to that cap, with a warning saying so. |
| --expires-hours <expires_hours> | integer range | — | The same lifetime in hours, for a link that should outlive a meeting and not a day. Clamped against the same caps as --expires-days; pass one or the other, not both. |
| --password <password> | text | — | Password-protect the link (account required). |
| --label <label> | text | — | Label to recognize the link in `share list`. |

退出码： 0 — completed

#### share list

List active share links in the workspace.

```bash
deepcell share list
```

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --file <filename> | text | — | Only links for this file. |

退出码： 0 — completed

#### share revoke

Revoke a share link by its id (see `share list`).

```bash
deepcell share revoke <share_id>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| share_id | text | 必填 |

退出码： 0 — completed

#### to-docx

Export one document's prose as a Word file.

deepcell to-docx <filename>
```bash
deepcell to-docx model.deepcell --doc variance_note -o variance-note.docx
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --doc <doc_id> | text | — | Document ID (required when the file has multiple documents). |
| --scenario <scenario_id> | text | — | Document scenario ID to export. |
| --output <out_path> | text | — | Output path (default: <filename>.docx). |
| --bundle | boolean | — | Link to sibling <name>.xlsx / <name>.pptx exports (the names to-excel and to-pptx write by default). Writes only the .docx — export those too. |

退出码： 0 — completed

#### to-excel

Export a .deepcell file to Excel format.

deepcell to-excel <filename>
```bash
deepcell to-excel model.deepcell -o model.xlsx
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --output <out_path> | text | — | Output file path (default: <filename>.xlsx). |
| --formulas | boolean | — | Export with live Excel formulas; --no-formulas writes values only. |
| --recalculate | boolean | — | Recompute formula values (needs formulas). |
| --scenario <scenario_id> | text | — | Document scenario ID to export (applies its VariableOverrides; exports that ONE scenario's numbers). |
| --switchable | boolean | — | Export EVERY scenario with a dropdown that switches between them in Excel. On by default when the document has scenarios to switch between and formulas are exported; --scenario or --no-switchable exports one scenario's numbers instead. |
| --variant <variant_id> | text | — | (unsupported) see --scenario for document scenarios. |

退出码： 0 — completed

#### to-pdf

Export a deck, a document or the Reasoning as a PDF.

deepcell to-pdf <filename>
```bash
deepcell to-pdf model.deepcell
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --from <source> | deck \| doc \| cheatsheet | deck | Which surface to render: the presentation deck, the prose document, or the Reasoning on A4 (the sheet the app calls the Cheatsheet). |
| --deck <deck_id> | text | — | Deck ID (required when the file has multiple decks). |
| --doc <doc_id> | text | — | Document ID (required when the file has multiple documents). |
| --scenario <scenario_id> | text | — | Document scenario ID to export. |
| --locale <locale> | en \| zh | — | Language of the Cheatsheet's own words — its headings and flags, not your text (default: en). Cheatsheet only. |
| --output <out_path> | text | — | Output path (default: <filename>_<deck\|doc\|cheatsheet>.pdf). |

退出码： 0 — completed

#### to-png

Render a deck's slides as PNG images, to look at them.

deepcell to-png <filename>
```bash
deepcell to-png model.deepcell --deck board --slides cover,risks --out slides
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --deck <deck_id> | text | — | Deck ID (required when the document has multiple decks). |
| --slides <slide_ids> | text | — | Comma-separated slide IDs to render, in that order (default: every slide). |
| --scenario <scenario_id> | text | — | Document scenario ID to render. |
| --scale <scale> | float range | 1 | Pixel density: 1 is the deck canvas (1280x720 at 16:9), 2 doubles it. |
| --out <out_dir> | text | — | Directory for the PNGs (default: <filename>-slides/). |

退出码： 0 — completed

#### to-pptx

Export one document-defined HTML deck as editable PowerPoint objects.

deepcell to-pptx <filename>
```bash
deepcell to-pptx model.deepcell --deck board -o board.pptx
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --deck <deck_id> | text | — | Deck ID (required when the document has multiple decks). |
| --scenario <scenario_id> | text | — | Document scenario ID to export. |
| --output <out_path> | text | — | Output path (default: <filename>.pptx). |

退出码： 0 — completed

#### viewer

Print the browser URL to open FILENAME.

deepcell viewer <filename>
```bash
deepcell viewer model.deepcell
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --open | boolean | — | Open the URL in the default browser. |

退出码： 0 — completed

### session — who you are and where your work lands

#### account delete

Permanently delete your account and everything it owns.

```bash
deepcell account delete
```

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --confirm-email <confirm_email> | text | — | Your account email. Prompted for if omitted. |
| --password <password> | text | — | Account password. Prompted for if the account has one. |
| --yes | boolean | — | Skip the interactive 'this is irreversible' confirmation. |

退出码： 0 — completed

#### account export

Download every record DeepCell holds about your account.

```bash
deepcell account export
```

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --output <out_path> | file | — | Write the export to this file instead of stdout. |

退出码： 0 — completed

#### doctor

Check this machine's setup: version, server, identity, workspace.

deepcell doctor
```bash
deepcell doctor -f json
```

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --timeout <timeout> | float | 10 | How long to wait for the server probe. |

退出码： 0 — completed

#### login

Authenticate with the DeepCell API.

```bash
deepcell login
```

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --email <email> | text | — | Email for direct login (headless/CI). |
| --password <password> | text | — | Password for direct login (headless/CI). |

退出码： 0 — completed

#### logout

Log out and remove stored credentials.

```bash
deepcell logout
```

退出码： 0 — completed

#### project create

Create a new project.

```bash
deepcell project create <name>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| name | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --slug <slug> | text | — | URL-friendly slug. Derived from the name, with a short random suffix, if omitted — slugs are unique across all projects. |
| --description <description> | text | "" | Project description. |

退出码： 0 — completed

#### project info

Show project details.

deepcell project info [slug]
```bash
deepcell project info
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| slug | text | 可选 |

退出码： 0 — completed

#### project list

List projects you belong to.

```bash
deepcell project list
```

退出码： 0 — completed

#### project use

Set the active project for subsequent commands.

deepcell project use <slug>
```bash
deepcell project use my-project
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| slug | text | 必填 |

退出码： 0 — completed

#### register

Create a new DeepCell account (headless/CI).

```bash
deepcell register
```

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --email <email> | text | — | Account email. |
| --password <password> | text | — | Account password (min 8 chars). |
| --name <display_name> | text | — | Your display name. |
| --locale <locale> | text | zh-CN | Locale (default: zh-CN). |

退出码： 0 — completed

#### upgrade

Check whether a newer deepcell CLI has been published.

```bash
deepcell upgrade
```

退出码： 0 — completed

#### upgrade check

Ask the package index right now and update the cached answer.

```bash
deepcell upgrade check
```

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --timeout <timeout> | float | 3 | How long to wait for each package index. |

退出码： 0 — completed

#### upgrade disable

Turn the automatic upgrade check off.

```bash
deepcell upgrade disable
```

退出码： 0 — completed

#### upgrade enable

Turn the automatic upgrade check on (the default).

```bash
deepcell upgrade enable
```

退出码： 0 — completed

#### upgrade status

Show the setting and the last cached answer.

```bash
deepcell upgrade status
```

退出码： 0 — completed

#### verify-email

Verify your email address.

```bash
deepcell verify-email
```

退出码： 0 — completed

#### whoami

Show the currently authenticated user.

```bash
deepcell whoami
```

退出码： 0 — completed

### sync — local folder <-> workspace

#### clone

Clone a workspace to a local folder.

deepcell clone <slug> [directory]
```bash
deepcell clone <slug>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| slug | text | 必填 |
| directory | text | 可选 |

退出码： 0 — completed

#### download

Download a file from the workspace to the local filesystem.

deepcell download <filename>
```bash
deepcell download cninfo-1224567890.pdf -o report.pdf
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --output <out_path> | text | — | Output file path (default: same as filename). |
| --revision <revision> | text | — | Download file at specific revision. |

退出码： 0 — completed

#### merge apply

Apply conflict resolutions to a pending merge session.

```bash
deepcell merge apply <session_id> --resolve <strategy>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| session_id | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --resolve <strategy> | ours \| theirs | 必填 | Resolution strategy for all conflicts. |
| --file <filename> | text | — | Write merged result to this local file. |

退出码： 0 — completed · 1 — conflict

#### merge preview

Preview a three-way merge for a .deepcell file.

deepcell merge preview <filename>
```bash
deepcell merge preview model.deepcell
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --base <base_rev> | text | — | Base revision SHA (defaults to last_sync_sha). |
| --theirs-rev <theirs_rev> | text | — | Revision for theirs (defaults to HEAD). |

退出码： 0 — completed · 1 — conflict

#### merge resolve

Resolve a sync conflict for a .deepcell file.

deepcell merge resolve <filename>
```bash
deepcell merge resolve model.deepcell
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| filename | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --ours | text | — | Resolve all conflicts with local values. |
| --theirs | text | — | Resolve all conflicts with remote values. |

退出码： 0 — completed · 1 — conflict

#### pull

Fetch the workspace's latest changes into the local folder.

```bash
deepcell pull
```

退出码： 0 — completed · 1 — conflict

#### push

Send local changes to the workspace.

```bash
deepcell push
```

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --message <message> | text | "" | Commit message for the push. |

退出码： 0 — completed · 1 — written-but-invalid

#### status

Show local changes vs last sync.

```bash
deepcell status
```

退出码： 0 — completed

### learn — the five reference surfaces

#### example

Complete, valid documents to copy the shape from.

```bash
deepcell example
```

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --pack <pack> | text | — | Only the core examples plus this pack's (default: every pack). |

退出码： 0 — completed

#### example get

Write an example document to a local file.

```bash
deepcell example get <name> --into <into>
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| name | text | 必填 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --into <into> | file | 必填 | Local path to write the document to. |
| --layer <layer> | skeleton \| full | full | Which document to seed from. |
| --force | boolean | — | Overwrite an existing file. |

退出码： 0 — completed

#### example list

List every example name — the same output as bare `deepcell example`.

```bash
deepcell example list
```

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --pack <pack> | text | — | Only the core examples plus this pack's (default: every pack). |

退出码： 0 — completed

#### example show

Print one layer of an example: skeleton, full, or transcript.

deepcell example show [name] [layer]
```bash
deepcell example show
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| name | text | 可选 |
| layer | text | 可选 |

退出码： 0 — completed

#### guide

Explain how DeepCell itself works.

deepcell guide [topics...]
```bash
deepcell guide orient/start
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| topics... | text | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --stage <stage> | text | — | Only this stage's topics (e.g. generate). |
| --pack <pack> | text | — | One domain pack: its vocabulary page, then its topics (e.g. finance). |
| --packs | boolean | — | List the domain packs. |
| --capabilities | boolean | — | Show the Jingwei/CLI/reference/transport capability contract. |
| --all | boolean | — | Also show the long-form reference pages and domain packs. |
| --search <search> | text | — | Topics whose name or description matches, across both catalogs. |

退出码： 0 — completed

#### help

Every command, flag, exit code and example as one document.

deepcell help [command...]
```bash
deepcell help
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| command... | text | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --stage <stage> | text | — | Only this stage's commands (e.g. generate). The six work stages are `deepcell guide`'s; session, sync and learn are help-only. |
| --search <search> | text | — | Commands whose name or summary matches TEXT. |

退出码： 0 — completed

#### ref

Look up legal values, and resolve any typed id — the format's or a document's.

deepcell ref [target...]
```bash
deepcell ref lint/hardcoded_literal_in_calc
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| target... | text | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --limit <limit> | integer | 40 | Maximum search results. |
| --file <filename> | text | — | With `search`: also search this .deepcell file's ids and labels (any language), printed first. |
| --source | boolean | — | With a document id: also print what it stores, verbatim — a slide's HTML, else its XML. Compose an edit to one slide from this. |
| --workspace <workspace_slug> | text | — | Override active workspace (with a document id or --file only). |

退出码： 0 — completed

#### rules

The invariants applicable to a .deepcell work shape.

deepcell rules [rule_ids...]
```bash
deepcell rules R2
```

| 参数 | 类型 | 是否必填 |
| --- | --- | --- |
| rule_ids... | text | 可选 |

| 选项 | 类型 | 默认值 | 作用 |
| --- | --- | --- | --- |
| --pack <pack> | text | — | Add this domain pack's rules when their selected surface applies. |
| --surfaces <surfaces> | text | — | Comma-separated selected surfaces: reasoning,spreadsheet,document,deck. Omit for universal rules only. |
| --all | boolean | — | Every rule, whatever work shape it applies to. Overrides --surfaces/--pack. |
| --full | boolean | — | Print every applicable rule in full, not just the index — one call, no per-rule round trips. |

退出码： 0 — completed

## 规则

每个模型都必须满足的不变量，每一条都有稳定的 id，供其他界面引用。凡是有 lint 支撑的规则，违反时打印的就是这里列出的代码——正是它把一条建议变成可以自查的约定。其余的规则在评审中人工核查。

```bash
deepcell rules R2
```

| 规则 | 内容 | 由什么保障 | Lint 代码 |
| --- | --- | --- | --- |
| rule:R1 | Native generation — Excel at the edges only | review | — |
| rule:R2 | Driver-based forecasts | lint | hardcoded_literal_in_calc |
| rule:R3 | One file per request, edited in place | review | — |
| rule:R4 | Forecasts must populate — verify by query-back | review | — |
| rule:R5 | Self-checking calculations | review | — |
| rule:R6 | Point-in-time results stay in their period | review | — |
| rule:R7 | Canonical naming and units | lint | monetary_units, duplicate_label_in_formula, placeholder_label |
| rule:R8 | Reasoning stays connected to the work it explains | lint | unanchored_claim, unanchored_assumption, exclusivity_assertion, body_itemrefs_mismatch |
| rule:R9 | Spreadsheet values have an intentional presentation | lint | unrendered_value, scalar_in_table_block |
| rule:R10 | A DCF carries a real FCF bridge | review | — |
| rule:R11 | Circular structures by deliberate convention — and seeded | lint | circular_calculation_unconverged, circular_calculation_slow |
| rule:R12 | Assumptions are grounded | lint | unsourced_actual, source_unused, input_grounding_gap, source_unaddressed, cites_row_unanchored, source_period_outside_filing, evidence_unanchored |
| rule:R13 | Statuses and periods declare what they mean | lint | undeclared_status_archetype, undeclared_context_state |
| rule:R14 | Analytical reasoning states its conclusion | lint | missing_apex_recommendation, dangling_conclusion_ref |
| rule:R15 | Prose that asserts a value must link it | lint | uncited_level, stale_literal_near_calc, typed_figure_in_title |
| rule:R16 | An outward address lives in exactly one place | review | — |
| rule:R17 | A cross-surface reference is a deepcell: URI | review | — |
| rule:R18 | Overriding a calculated cell removes its formula | review | — |
| rule:R19 | Analytical reasoning states the question it answers | lint | dangling_key_question_ref, ambiguous_key_question, key_question_not_answered, answers_non_question, asks_about_non_question, unreviewed_key_question |

## 范例

可以直接拿来起步的完整、合法文档，选取标准是它展示的机制，而不是所属行业。它们会在 CI 中依据各自的构建记录重建并做 lint 检查，因此不会是过时的片段。复制某一条下面的命令，即可用它初始化一个文件。

| 范例 | 展示的机制 | 领域 |
| --- | --- | --- |
| charts/gantt-schedule | Gantt intervals and milestones on a calendar axis | published five-task schedule illustration |
| charts/mekko-mix | Mekko variable-width categories with spreadsheet-owned share and total series | published produce mix illustration |
| charts/metro-produce-pilot | One decision traced through spreadsheet-owned waterfall, Mekko, Gantt and a bound three-slide deck | illustrative grocery produce pilot |
| charts/waterfall-bridge | waterfall steps, calculated totals, connectors and display-only subtotal labels | published bridge illustration |
| decision/board-readout | qualitative board readout — a question, its answer, the counter-case and the evidence gates, delivered as a memo and a three-slide deck bound to the same nodes, with no grid | platform strategy / board governance |
| decision/vendor-diligence | qualitative evidence-to-decision graph with a linked memo and no grid | procurement / security diligence |
| finance/cn-a-share-3s-dcf | extraction-based raw/model layering with filing provenance | A-share equity research |
| finance/dcf-memo | a compact single-stage DCF whose valuation memo quotes every figure through live cell references, with the terminal share as the stated weakness | corporate finance / valuation memo |
| finance/ic-deck | a styled multi-slide deck bound onto a finished model, then exported | investment committee readout |
| finance/saas-dcf | the full three-statement + DCF loop | finance |
| ingest/board-pack | faithful workbook import — row/column mapping, converted formulas, per-cell provenance | public transport, board reporting |
| manufacturing/line-debottleneck | an author-drawn SVG exhibit whose geometry carries the argument | industrial manufacturing, plant throughput |
| ops/headcount-plan | items × contexts, drivers, and scenarios | HR / operations |
| ops/variance-to-plan | monthly plan-versus-actual review — two statuses on every line, derived variances that read both, a zero self-check, and a memo that attributes the gap | retail store operations |
| product/launch-decision | small all-four-surface premise change with selective reassessment | product launch governance |
| project/build-budget | status axis (committed / actual / forecast) and variance self-checks | construction, grants |
| research/experiment-results | custom dimensions, actual vs expected status, and a <Document> write-up | science / experimental research |
| supply/inventory-plan | sensitivity blocks | logistics |

### charts/gantt-schedule

Bind start, end, and milestone spreadsheet Items to a shared Gantt chart. Dates are transcribed from the public think-cell datasheet. The separate public chart screenshot informs layout only; it uses different dates.

```bash
deepcell example get charts/gantt-schedule --into <into>
```

### charts/mekko-mix

Calculate totals and shares as spreadsheet Items; use the total series for category width and share series for stacks. The numeric inputs follow the think-cell public manual; adjusted labels are DeepCell-authored. Default segment and legend colors follow DeepCell's categorical chart tokens.

```bash
deepcell example get charts/mekko-mix --into <into>
```

### charts/metro-produce-pilot

Start with a decision question and three supporting claims. Bind the profit bridge, market shares and launch dates to spreadsheet Items, then bind three deck charts and their takeaway text to the same model. Slide-owned leaders connect quoted key points to stable chart point or difference-annotation IDs in both deck renderers. The economics quote targets the model-bound gap between current and pilot run rates, not either bar alone. The values and dates are synthetic planning inputs, not observations of a real retailer.

```bash
deepcell example get charts/metro-produce-pilot --into <into>
```

### charts/waterfall-bridge

Keep waterfall subtotal arithmetic in spreadsheet Items, bind step roles and connectors in ChartSpec, then inspect default and adjusted shared scenes. Numeric cells follow the think-cell public manual; the adjusted style is DeepCell-authored, not a pixel-identical output claim.

```bash
deepcell example get charts/waterfall-bridge --into <into>
```

### decision/board-readout

The shortest complete path from a board question to a readout. Reasoning is written first and declares the question, the recommendation, the counter and the gates the evidence must pass; the memo quotes those nodes; the deck binds its cover and its evidence page to the same nodes and to the sources, so no slide restates a sentence the argument does not hold. The surfaces are declared up front, so `describe --lint` says which promise is still open.

```bash
deepcell example get decision/board-readout --into <into>
```

### decision/vendor-diligence

A complete decision can be qualitative: source-backed Evidence and explicit Assumptions connect to a declared conclusion, while the memo links those live nodes instead of inventing Items, Contexts, Values, a Sheet, or a Block.

```bash
deepcell example get decision/vendor-diligence --into <into>
```

### finance/cn-a-share-3s-dcf

An A-share issuer's three consolidated CAS statements pulled from cninfo with `deepcell ingest cn` and stored as an immutable raw layer — 元, full precision, bilingual labels, one <Source kind="filing"> whose <Cites at="page:N"> deep-link each statement — with historical mapping calcs onto the CAS chart's `_Model` ids, six mapping checks that read 0 on both filed years, and a P&L + DCF projection (the model-scopes default) on top.

```bash
deepcell example get finance/cn-a-share-3s-dcf --into <into>
```

### finance/dcf-memo

The shortest complete Reasoning → Spreadsheet → Document valuation. One actual base year, three forecast years driven by five rate items, a terminal value, and an enterprise value; the memo quotes the cells rather than restating them, and the argument names what the reader should push on — the terminal value carries five sixths of the answer. The surfaces are declared first, so `describe --lint` says which promise is still open.

```bash
deepcell example get finance/dcf-memo --into <into>
```

### finance/ic-deck

The model is done and the audience is a committee. Starting from the finished Lumenwave DCF, the transcript records the recommendation as a Claim first, then adds one deck, applies the consulting style pack verbatim, and writes four slides — the cover that asks the committee's question and nothing else, the answer that states the decision with its cash-flow exhibit, the page that says where the value is decided, and a closing slide that says what would change it, each a different shape on the pack's vocabulary — whose every number, chart, sentence of reasoning and footnote is a binding against the model's real ids — value, series, chart, reasoning and source — before reading `describe --lint` for the deck codes, exporting the .pptx and handing a reviewer a share link.

```bash
deepcell example get finance/ic-deck --into <into>
```

### finance/saas-dcf

A linked income statement, balance sheet and cash flow statement feeding an unlevered DCF whose every forecast number traces to a driver item — with the three self-checks (BS_Check, CF_Recon, EV_Check) that prove the loop closed.

```bash
deepcell example get finance/saas-dcf --into <into>
```

### ingest/board-pack

One `deepcell import` turns a board pack into the file — statuses with an archetype, contexts with a state, scale and currency on every monetary row, the pack's own formulas as live calcs, and one workbook Source citing the cell each number came from — and the work is what comes before it (reading the sheet into two JSON payloads) and after it (the round trip, verified before anything is built on top). Nothing is projected: three closed months and their quarter go in, and the same come out.

```bash
deepcell example get ingest/board-pack --into <into>
```

### manufacturing/line-debottleneck

The measured line is already in the file and the numbers are not in dispute; what a table of five station cycle times cannot say is that the leak test's rejects re-enter the line upstream, at the weld cell. So the exhibit is a drawing. The transcript records the judgement as a Claim first, adds one deck, applies the product pack verbatim plus the ten classes the drawing needs, and writes an inline `<svg>` on the shape subset — `<defs><marker>` arrowheads reached by a local `url(#id)` fragment, colour and weight taken from the pack's own tokens so a restyle carries the drawing with it. Every figure stays bound, beside the drawing: inside one a `<dc-value>` is drawn only within a `<text>`, as a live `<tspan>`, and paints nothing anywhere else (`deck_bind_in_svg`).

```bash
deepcell example get manufacturing/line-debottleneck --into <into>
```

### ops/headcount-plan

Two hiring plans out of one model — every derived number traces to an editable driver row, and the second scenario is the handful of cells that differ rather than a second copy of the file. A check row rolls the whole group forward by a second route and reads 0 under both scenarios, and a <Document> summary quotes the same Q4 cells twice — once per scenario, by the `@scenario` tail of the cell locator. An average of a count lands on halves, so it keeps `count` and takes its one decimal from an `item:` format rule rather than a change of type.

```bash
deepcell example get ops/headcount-plan --into <into>
```

### ops/variance-to-plan

The shortest complete variance-to-plan: plan and actual live on the Status dimension of the same cells, the variances are calculations that read both statuses (`Item[ctx]#actual - Item[ctx]#plan`), one check proves the three variances reconcile, and the memo explains the month by quoting the cells and the claim that attributes the gap. The surfaces are declared first, so `describe --lint` says which promise is still open.

```bash
deepcell example get ops/variance-to-plan --into <into>
```

### product/launch-decision

One calculation supports a declared launch decision, a memo, and a one-slide deck. The transcript starts from the before-state, changes one demand premise, discovers impact and backlinks, preserves the conclusion after checking its boundary, reconnects the replacement assumption, and verifies every selected surface.

```bash
deepcell example get product/launch-decision --into <into>
```

### project/build-budget

Three readings of the same cell live on the Status dimension — not in three parallel item trees — a calc reaches across them with `Item[ctx]#status`, and every allocation and variance carries a cross-check whose correct answer is known to be 0.

```bash
deepcell example get project/build-budget --into <into>
```

### research/experiment-results

A third axis and a second reading on the same row — the phenotype class is a custom Dimension that slices every data row instead of doubling it, and observed sits beside predicted under one item id rather than under two. The data is Mendel's published F2 counts for his seven traits, so the file has to carry a real result and a real objection to it at once: the counts fit 3:1, and CHIDIST says they fit it more closely than sampling error alone explains. The readout itself ships as a <Document>: every number in the prose is a link, so re-running the counts refreshes the values and identifies prose whose surrounding judgment must be reassessed explicitly.

```bash
deepcell example get research/experiment-results --into <into>
```

### supply/inventory-plan

Sensitivity is a native `blockType="sensitivity"` block whose every cell is a transient recompute of the model — never a ladder of near-duplicate perturbation items — shown in all three legal shapes: 2-variable grid, 1-variable table, and scenario comparison.

```bash
deepcell example get supply/inventory-plan --into <into>
```