# The DeepCell CLI, in full

Five surfaces, every guide topic, every command and every rule — generated from the CLI itself, so what is on this page is what your terminal answers.

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

## Start here

Install the CLI. No account is needed to begin — the first call mints an anonymous session, and everything on this page works from a cold install.

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

Windows (PowerShell)
```powershell
irm https://beta.deepcell.net/install.ps1 | iex
```

Then check the install in one call: version, whether the service is reachable, who you are, and which workspace is active.

```bash
deepcell doctor
```

Read the guided walkthrough, then list what is in your workspace. If the second one prints, you are connected.

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

Signing in is optional and belongs after your first file, not before it. It keeps your work beyond the anonymous session, lifts the anonymous limits, and lets you share what you build.

```bash
deepcell login
```

## The five surfaces

The reference is split by the question you are asking at that instant, because each kind of knowledge has a different shape, a different read frequency, and a different risk of going stale. Reach for the one that matches your question rather than reading the set.

| Surface | The question you are asking | What it answers |
| --- | --- | --- |
| deepcell help | How do I invoke this exactly? | Every command, flag, exit code and example as one document. |
| deepcell rules | What must always hold? | The non-negotiable invariants every .deepcell model must satisfy. |
| deepcell guide | What is the procedure for this stage? | Explain how DeepCell itself works. |
| deepcell ref | What values are legal here? | Look up legal values, and resolve any typed id. |
| deepcell example get | What does a correct one look like? | Write an example document to a local file. |

Two of them — the invocation reference and the legal-values reference — are derived from the implementation, so they cannot drift from it. The other three are written by hand and tied back mechanically: every id they cite has to resolve, and CI fails when one does not.

This page is not a sixth surface. It is a rendering of those five, built from the same manifest the CLI serves, so the two cannot describe different commands. Manifest version: 0.3.0

## Every guide topic

Topics are ordered procedure, grouped by the stage of the work they belong to. Read the one for the stage you are in rather than the whole index. Print any of them from a terminal:

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

| Topic | Stage | What it covers |
| --- | --- | --- |
| orient/choose-shape | orient | What you are building, and which examples and domain pack to read for it |
| orient/concepts | orient | Item, Context, Status, Scenario, Value, Calc — the six words everything is built from |
| orient/how-to-work | orient | You produce work that someone else will question. It lands in a `.deepcell` |
| orient/start | orient | Look before you build: check the setup, pick the workspace, read what is there |
| ingest/tabular | ingest | An xlsx or csv becomes items and contexts: dimension mapping, then provenance |
| generate/calcs | generate | Define the relationship once; the engine produces every number from it |
| generate/first-file | generate | Empty workspace to one valid `.deepcell` file you can then build on |
| generate/structure | generate | Rows are Items, columns are Contexts, and a third axis is a custom Dimension |
| generate/values | generate | Literal cells are for inputs only, and every driver must actually hold one |
| generate/whole-doc | generate | Authoring a complete document as one XML write, and when that beats defs ops |
| revise/history | revise | Versions, variants, and moving a workspace between the cloud and a local folder |
| revise/reasoning | revise | Record why the model says what it says — and supersede rather than delete |
| revise/scenarios | revise | What-if analysis over one file — no copies, no forked models |
| revise/structure | revise | What add, rename, reorder and delete each break — and what the ops fix for you |
| revise/values | revise | Changing numbers that already exist — one cell, many cells, or raw XML |
| verify/lint | verify | One of three verification moves, and not the one that catches the worst failure |
| verify/query-back | verify | Read the forecast cells back — an empty grid is the failure no linter reports |
| verify/review | verify | Eight dimensions, each independently runnable, each demanding cited evidence |
| present/charts | present | Chart blocks, key-value cards, text notes, and the results-first Summary sheet |
| present/decks | present | HTML slides whose numbers come from the document itself, through typed bindings |
| present/deliver | present | Getting the result to someone: workbench link, share link, xlsx, pptx |
| present/layout | present | Sheets, blocks, expansions, formats, and sensitivity: what renders, and where |
| present/prose | present | Writing the `<Document>` body, and addressing anything in the file from it |
| overview | reference | Template — three-statement model architecture: sheet layout, item order ranges, and the IS/BS/CF golden loop |
| assumptions | reference | Template — assumptions sheet: driver categories, order ranges, and why drivers are Values while anything derived is a CalcDef |
| income-statement | reference | Template — income statement items and formulas, revenue through net income |
| balance-sheet | reference | Template — balance sheet items and formulas, plus the assets = liabilities + equity check |
| cash-flow | reference | Template — cash flow statement: operating/investing/financing sections and the cash reconciliation |
| dcf | reference | Template — DCF valuation: free cash flow build, WACC, terminal value, and the equity bridge |
| scenarios | reference | Template — worked bull/base/bear setup: which variables to override and by how much (for the mechanics, read scenario-definitions) |
| validation | reference | Template — integrity check items every model should carry (balance check, cash reconciliation, coverage ratios) |
| quick-start | reference | Template index for financial models — which of the finance-pack templates to read for a 3-statement, DCF or scenario build (to begin a task, read orient/start) |
| orchestrator | reference | How to run DeepCell work — what the job is, when it is done, and how to look things up instead of guessing |
| calc-engine | reference | How the calc engine recomputes — define relationships, not values |
| bank | reference | Template — bank / NIM model: rate × balance grid, net interest income, efficiency ratio, provision |
| insurance | reference | Template — insurance model: earned premium, loss/expense ratios, combined ratio, underwriting result |
| reit | reference | Template — REIT model: NOI, FFO, AFFO, real-estate depreciation add-back |
| custom-dimensions | reference | Custom dimensions — multi-segment analysis (geography, product, unit, channel) |
| formula-patterns | reference | Formula patterns — advanced modeling constructs and the formula quick guide |
| xml-schema-reference | reference | XML skeleton for the core sections in document order — Metadata, Status, Context, Items, Calculations, Presentation, Values, Dimensions |
| build-from-scratch | reference | Build playbook — starting with no existing .deepcell file, from empty workspace to a valid model |
| build-on-historicals | reference | Build playbook — adding projections on top of categorized historicals produced by an extractor |
| account-categorization | reference | Mapping a company's own statement labels onto a standard chart of accounts, without editing the extraction |
| chart-of-accounts-gaap | reference | Template — US GAAP standard chart of accounts (order 4000-4299), item ids matching the statement templates |
| chart-of-accounts-ifrs | reference | Template — IFRS standard chart of accounts, and where it diverges from US GAAP |
| chart-of-accounts-cas | reference | Template — Chinese Accounting Standards (企业会计准则) chart of accounts for A-share filers |
| non-gaap-metrics | reference | Template — non-GAAP adjusted metrics (order 4300-4399): adjusted EBITDA, net income, and EPS |
| calc-specificity | reference | Calc status & scenario specificity — how multiple calcs for one (item, context) slot are disambiguated |
| status-resolution | reference | Which stored status a read answers with — the read side of the status axis, and the diagnostics emitted when it had to choose |
| status-semantics | reference | What a status MEANS — the archetype vocabulary on <Status> and the period state on <Context>, which replaced guessing from id spelling |
| items | reference | ItemDefinitions — data types, scale, currency, and value conventions |
| functions | reference | Built-in formula functions reference |
| sync | reference | Local sync workflow (clone, pull, push) |
| exit-codes | reference | What a nonzero exit means per command — written-but-invalid vs rolled-back vs partial |
| presentations | reference | PresentationDefinitions — core Sheet/Block layout, membership, ordering, and coverage |
| presentation-expansions | reference | Presentation block expansions — status/scenario columns and custom-dimension rows |
| presentation-charts | reference | Presentation charts, dashboards, key-value/text blocks, and results-first summaries |
| decks | reference | HTML Deck structure, typed bindings, slide markup, static charts, and security |
| deck-styling | reference | HTML Deck institutional house style — layout, typography, palette, charts, and CSS starter |
| deck-authoring | reference | HTML Deck CLI authoring, validation, viewer deep links, limits, and troubleshooting |
| surface-ownership | reference | Who owns a number, a conclusion, a paragraph and a slide — the cross-surface editing contract |
| document-authoring | reference | <Document> prose — the link-everything rule, the markdown dialect, anchors, embeds, and the CLI |
| deepcell-uri | reference | The deepcell: reference — grammar, per-kind locators, the formula-grammar conversion, and id rules |
| data-sources | reference | SourceDefinitions — where a number came from; the one place an outward address lives |
| scenario-definitions | reference | ScenarioDefinitions — what-if scenario analysis |
| format-definitions | reference | FormatDefinitions — cell formatting rules for viewer and Excel export |
| format-precedence | reference | FormatDefinitions — precedence chain, FormatStatus inference, number-format resolution |
| reasoning | reference | Reasoning — typed knowledge graph (Claim, Assumption, Evidence, Argument) |
| reasoning-anti-patterns | reference | Common reasoning mistakes with corrected examples |
| reasoning-checklist | reference | Pre-build checklist for valid <Reasoning> sections |
| sharing | reference | Share links — give anyone a browser view of one file (incl. anonymous sessions) |
| viewer | reference | Web viewer — view .deepcell files in the browser |
| replace | reference | String-replacement editing with deepcell replace |
| upload | reference | Uploading and creating .deepcell files (write and import commands) |
| schema-matching | reference | Mapping external data (xlsx/csv) to .deepcell item and context dimensions |
| values-vs-defs-ops | reference | Two-call pattern: /batch-edit (Values) vs /apply-defs-ops (structural) |
| sensitivity | reference | Sensitivity blocks — 2-variable data tables, 1-variable data tables, scenario comparisons |
| house-rules | reference | House rules — the non-negotiable invariants every model must satisfy |
| review-dimensions | reference | Review dimensions — the model audit checklist (integrity, formulas, coverage, sanity, grounding, reasoning, intent, presentation) |
| model-scopes | reference | Choosing model scope — P&L+DCF default, 3-statement triggers, industry models |
| sec-extraction | reference | SEC extraction — raw historical layer, model mapping layer, provenance rules |
| cn-extraction | reference | A-share (cninfo) extraction — CAS statements from report PDFs, #page deep links, canonical item map |
| excel-import | reference | Excel import — dimension mapping, formula conversion, excel_import provenance |

## Every command

Every command, with the shape of its invocation, its flags and their defaults, what each exit code means, and one runnable example. The whole catalog is also one call away as machine-readable data — worth caching once instead of paying for a round trip per command:

```bash
deepcell help
```

### account delete

Permanently delete your account and everything it owns.

```bash
deepcell account delete
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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. |

Exit codes: 0 — completed

### account export

Download every record DeepCell holds about your account.

```bash
deepcell account export
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --output <out_path> | file | — | Write the export to this file instead of stdout. |

Exit codes: 0 — completed

### assumption impact

List Claims that depend_on ASSUMPTION_ID.

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

Exit codes: 0 — completed · 2 — unparseable-document

### cat

Print file content (XML) to stdout.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Show file at specific revision. |
| --workspace <workspace_slug> | text | — | Override active workspace. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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'. |

Exit codes: 0 — completed

### claim falsified

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

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

Exit codes: 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>
```

Exit codes: 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>
```

Exit codes: 0 — completed · 2 — unparseable-document

### clone

Clone a workspace to a local folder.

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

Exit codes: 0 — completed

### commit

Commit changes staged on the server by something other than you.

```bash
deepcell commit
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --message <message> | text | — | Commit message. |

Exit codes: 0 — completed · 1 — written-but-invalid

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --sheet <sheet_id> | text | required | Sheet containing the block. |
| --block <block_id> | text | required | blockId to edit. |
| --axis <axis> | rows \| columns | required | Which axis to edit: 'rows' (the block's @itemOrders) or 'columns' (its @contextRefs). |
| --member <member> | item \| context | required | What kind of id --ref is. Pair 'item' with rows, 'context' with columns. |
| --ref <ref> | text | required | The item id or context id to add. |
| --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. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --sheet <sheet_id> | text | required | Sheet to add the block to. |
| --block-type <block_type> | text | required | One of: table, chart, sensitivity, key_value, text. The server stores any string, but the renderer skips a block whose type it does not know, so anything else is written and never drawn. |
| --name <name> | text | required | Display name / section heading. |
| --item-orders <item_orders> | text | — | Comma-separated item ids forming the block's rows, in order (e.g. 'revenue,cogs,gross_profit'). 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'). Omit to show every context. |
| --index <index> | integer | — | Insertion index within the sheet (default: append at the end). |
| --chart-type <chart_type> | bar \| bar_stacked \| bar_horizontal \| line \| area \| pie \| donut \| waterfall \| range_bar | — | Chart type (chart blocks only). 'waterfall' bridges deltas between declared totals; 'range_bar' draws a low..high band per category (the football field). |
| --category-axis <category_axis> | context \| item | — | Which dimension is the category axis (chart blocks only). |
| --grid-span <grid_span> | single \| full | — | Dashboard layout footprint (chart blocks only). |
| --total-item-refs <total_item_refs> | text | — | Whitespace/comma-separated refs naming the plotted categories that rest on the baseline instead of floating on the running sum (--chart-type=waterfall only). Declared, never inferred: omit it and every step is a delta. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --item <item_id> | text | required | 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. Omit to let the server assign one — but an auto id is what `defs delete-calc` and a claim's --calc-ref must then quote, so choose your own when the calc has to be citable. |
| --formula <formula> | text | required | 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') 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 the item lacks a literal value. |
| --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. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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 | — | Explicit contextRef (else server-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 — the question the A/E suffix on a context id used to answer by accident. 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. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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 markdown body (else empty). |
| --index <index> | integer | — | Position among documents. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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'
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --rule <rule_strs> | text | — | One rule as semicolon-separated key=value pairs, e.g. 'target=default; font_color=#000000; number_format=#,##0'. Commas inside a value (such as Excel number formats) are preserved. Repeat the flag for multiple rules. Keys: target, font_color, background_color, font_weight, font_style, font_name, font_size, text_align, indent, number_format, border_top/bottom/left/right. |
| --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 guide format-precedence`. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --name <name> | text | required | Item name (itemId basis). |
| --label <label> | text | — | Display label (e.g. 'Gross Margin %'); defaults to a humanized form of --name. |
| --level <level> | integer | — | Hierarchy level (0-3). |
| --parent <parent_item_id> | text | — | Parent itemId (omit for root). |
| --index <index> | integer | — | Position among siblings (omit to append at end). |
| --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). |
| --currency <currency> | text | — | Currency element (ISO code, e.g. 'USD'). |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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 | — | Explicit contextRef (else server-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 — the question the A/E suffix on a context id used to answer by accident. 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. |
| --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. |

Exit codes: 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'
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --target <target> | text | required | Rule @target selector (see `deepcell guide format-definitions`). |
| --bg-color <background_color> | text | — | Hex color '#RRGGBB' for backgroundColor. |
| --font-color <font_color> | text | — | Hex color '#RRGGBB' for fontColor. |
| --font-weight <font_weight> | text | — | e.g. 'bold' / 'normal'. |
| --font-style <font_style> | text | — | e.g. '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, e.g. '#,##0'. |
| --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. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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 | — | (removed) @baseScenarioRef no longer exists — see `deepcell guide scenario-definitions`. |
| --context <context_ref> | text | — | Explicit contextRef. |
| --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. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --sheet <sheet_id> | text | required | Sheet to add the block to. |
| --name <name> | text | required | 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> | filename | required | JSON with {"axes": [...], "outputs": [...]} (use "-" for stdin). |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --label <label> | text | required | Sheet tab label, e.g. 'Dashboard'. |
| --index <index> | integer range | — | 0-based position among the sheets (default: append at the end). |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --id <source_id> | text | required | 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, document, person, derived, other. 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[,SUFFIX] \| page:47 \| sheet:Name!A1:B9 \| row:1042 \| col:arr \| t:00:14:32 \| anchor:id. |
| --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 | — | CSV of itemRefs this source backs. |
| --contexts <context_refs> | text | — | CSV of contextRefs. 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. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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 | — | Explicit statusRef. |
| --color <color> | text | — | (removed) 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. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --ops-file <ops_file> | filename | — | JSON file with an `ops` array (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. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --sheet <sheet_id> | text | required | Sheet containing the block. |
| --block <block_id> | text | required | blockId to edit. |
| --axis <axis> | rows \| columns | required | Which axis to edit: 'rows' (the block's @itemOrders) or 'columns' (its @contextRefs). |
| --ref <ref> | text | required | The item id or context id to remove. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 0 — completed · 1 — nothing-changed

### defs delete-block

Delete a Block from a Sheet.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --sheet <sheet_id> | text | required | Sheet containing the block. |
| --block <block_id> | text | required | blockId to delete. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 0 — completed · 1 — nothing-changed

### defs delete-calc

Delete a CalculationDefinition by calcId.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --cascade | boolean | — | Also delete all descendants. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --index <index> | integer | — | Delete the rule at this position. |
| --target <target> | text | — | Delete the first rule with this @target. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 0 — completed · 1 — nothing-changed

### defs delete-scenario

Delete a ScenarioDefinition by its contextRef.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --id <source_id> | text | required | sourceId to delete. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 0 — completed · 1 — nothing-changed

### defs delete-status

Delete a StatusDefinition by its statusRef.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 0 — completed · 1 — nothing-changed

### defs header set

Set or replace a Header property.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --type <prop_type> | string \| number \| boolean \| datetime | string | Property type tag written into <Property @type>. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 0 — completed · 1 — nothing-changed

### defs header unset

Delete a Header property.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --workspace <workspace_slug> | text | — | Override active workspace. |

Exit codes: 0 — completed · 1 — read-only-check

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --sheet <sheet_id> | text | required | Sheet containing the block. |
| --block <block_id> | text | required | blockId to rename. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --sheet <sheet_id> | text | required | Sheet containing the block. |
| --block <block_id> | text | required | blockId to edit. |
| --axis <axis> | rows \| columns | required | Which axis to edit: 'rows' (the block's @itemOrders) or 'columns' (its @contextRefs). |
| --ref <ref> | text | required | The item id or context id to move. |
| --to-index <to_index> | integer range | required | Final 0-based position on the axis. 0 = first row / leftmost column. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --sheet <sheet_id> | text | required | Sheet containing the block. |
| --block <block_id> | text | required | blockId to move. |
| --to-index <to_index> | integer range | required | Final 0-based position among the sheet's blocks. 0 = topmost. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 0 — completed · 1 — nothing-changed

### defs reorder-contexts

Move a Context to a new position in the contexts list.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --to-index <to_index> | integer | required | 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. |
| --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. |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --to-index <to_index> | integer range | required | 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. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --to-index <to_index> | integer range | required | Final 0-based position among the sheets. 0 = leftmost tab. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --sheet <sheet_id> | text | required | Sheet containing the block. |
| --block <block_id> | text | required | blockId of the block to edit. |
| --status-expansion <status_expansion> | none \| columns | — | Side-by-side status-column layout. 'columns' lays each status in --status-refs out as its own run of context columns; '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 | — | Custom-dimension member sub-rows. 'rows' lays each member of --dim-ref out as a contiguous sub-row under its item; '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. |
| --scenario-expansion <scenario_expansion> | none \| columns | — | Side-by-side scenario-column layout. 'columns' lays each scenario in --scenario-refs out as its own run of context columns; '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> | bar \| bar_stacked \| bar_horizontal \| line \| area \| pie \| donut \| waterfall \| range_bar | — | Chart type (chart blocks only). 'waterfall' bridges deltas between declared totals; 'range_bar' draws a low..high band per category (the football field). |
| --category-axis <category_axis> | context \| item | — | Which dimension is the category axis (chart blocks only). |
| --grid-span <grid_span> | single \| full | — | Dashboard layout footprint (chart blocks only). |
| --total-item-refs <total_item_refs> | text | — | Whitespace/comma-separated refs naming the plotted categories that rest on the baseline instead of floating on the running sum (--chart-type=waterfall only). Declared, never inferred: omit it and every step is a delta. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 0 — completed · 1 — nothing-changed

### defs set-format

Set cell/row/column formatting (resolves the governing <Format>).

deepcell defs set-format <filename> --sheet-id <sheet_id> --item-ref <item_ref> --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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --sheet-id <sheet_id> | text | required | Sheet id of the cell. |
| --block-id <block_id> | text | — | Governing block id (resolves @formatRef). |
| --item-ref <item_ref> | text | required | Item ref of the cell. |
| --context-ref <context_ref> | text | — | Context ref (required for cell/column scope). |
| --scope <scope> | cell \| item \| context | required | cell:ITEM:CONTEXT \| item:ITEM \| context:CONTEXT |
| --number-format <number_format> | text | — | Excel pattern, e.g. '#,##0'. |
| --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. |
| --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. |

Exit codes: 0 — completed · 1 — nothing-changed

### defs set-source-cites

Replace which cells a <Source> backs.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --id <source_id> | text | required | sourceId whose coverage to replace. |
| --items <item_refs> | text | — | CSV of itemRefs this source backs. |
| --contexts <context_refs> | text | — | CSV of contextRefs. 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. |
| --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. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --workspace <workspace_slug> | text | — | Override active workspace. |

Exit codes: 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'
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --formula <formula> | text | — | Replace the formula. |
| --context <context_ref> | text | — | Change contextRef. |
| --scenario <scenario_ref> | text | — | Change scenarioRef. |
| --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. |
| --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. |

Exit codes: 0 — completed · 1 — nothing-changed

### defs update-context

Patch a Context's name / status / kind; only 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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 — the question the A/E suffix on a context id used to answer by accident. 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. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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. |
| --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. |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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 guide format-precedence`. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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. |
| --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. |
| --currency <currency> | text | — | Set Currency element (ISO code). |
| --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. |
| --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. |

Exit codes: 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'
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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. |
| --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. |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --sheet <sheet_id> | text | required | Sheet containing the block. |
| --block <block_id> | text | required | blockId of the block to edit. |
| --name <name> | text | — | New display name. |
| --format-ref <format_ref> | text | — | New FormatDefinitions id. |
| --spec-file <spec_file> | filename | — | JSON with {"axes": [...], "outputs": [...]} to replace both. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking. |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --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. |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --id <source_id> | text | required | 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. |
| --description <description> | text | — | New description. Pass '' to clear. |
| --at <at> | text | — | New default position. |
| --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. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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. |
| --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. |

Exit codes: 0 — completed · 1 — nothing-changed

### describe

Show a document's shape: items, contexts, scenarios, statuses, sheets.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --include-reasoning | boolean | — | Append a compact summary of the document reasoning graph. |
| --scenario <scenario_id> | text | — | Scenario ID whose value overrides to apply. |
| --lint | boolean | — | Include canonical structural findings and exit non-zero on findings. |
| --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`. |
| --workspace <workspace_slug> | text | — | Override active workspace. |

Exit codes: 0 — completed · 1 — read-only-check

### diff

Show diff between two revisions (like git diff).

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --file <filename> | text | — | Filter diff by filename. |

Exit codes: 0 — completed

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --target <target> | text | required | Reference to invert, e.g. 'claim/t_hold'. |

Exit codes: 0 — completed

### doc blocks

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

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --doc <doc_id> | text | — | Document ID (default: the first). |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --doc <doc_id> | text | required | Document ID. |
| --block <block_id> | text | required | Block id to delete. |
| --rationale <rationale> | text | — | Commit message recording why. |
| --revision <revision> | text | — | Compare-and-swap token from `cat`. |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --doc <doc_id> | text | required | Document ID. |
| --after <after_block_id> | text | — | Insert after this block id. Omit to insert at the top. |
| --markdown-file <markdown_file> | file | required | File holding the new block's markdown. |
| --rationale <rationale> | text | — | Commit message recording why. |
| --revision <revision> | text | — | Compare-and-swap token from `cat`. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --doc <doc_id> | text | — | Restrict to one document. |
| --unresolved | boolean | — | Only references that did not resolve. |

Exit codes: 0 — completed

### doc lint

Check a document's references.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --doc <doc_id> | text | — | Restrict to one document. |
| --strict | boolean | — | Also flag numerals that match a modelled value but are typed, not linked. |

Exit codes: 0 — completed

### doc list

List every <Document> in the file.

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

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --doc <doc_id> | text | required | Document ID. |
| --block <block_id> | text | required | 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`. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --doc <doc_id> | text | — | Document ID (default: the first). |

Exit codes: 0 — completed

### doc patch-body

Replace one anchored section of a document.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --doc <doc_id> | text | required | Document ID. |
| --anchor <anchor> | text | required | Explicit {#id} anchor of the section to replace. |
| --markdown <markdown> | text | required | Replacement markdown for that section. |
| --rationale <rationale> | text | — | Commit message recording why. |
| --revision <revision> | text | — | Compare-and-swap token from `cat`. |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --doc <doc_id> | text | required | Document ID. |
| --block <block_id> | text | required | Block id from `deepcell doc blocks`. |
| --markdown-file <markdown_file> | file | required | File holding the replacement markdown. |
| --rationale <rationale> | text | — | Commit message recording why. |
| --revision <revision> | text | — | Compare-and-swap token from `cat`. |

Exit codes: 0 — completed

### doc set-body

Replace a document's whole markdown 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'
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --doc <doc_id> | text | required | Document ID. |
| --body-file <body_file> | file | required | File holding the new markdown body. |
| --rationale <rationale> | text | — | Commit message recording why. |
| --revision <revision> | text | — | Compare-and-swap token from `cat` (refuses if the file moved). |

Exit codes: 0 — completed

### doc show

Print one document.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --doc <doc_id> | text | — | Document ID (default: the first). |
| --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. |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --doc <doc_id> | text | required | Document ID. |
| --rationale <rationale> | text | — | Commit message recording why. |
| --revision <revision> | text | — | Compare-and-swap token from `cat`. |

Exit codes: 0 — completed

### doctor

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

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --timeout <timeout> | float | 10 | How long to wait for the server probe. |

Exit codes: 0 — completed

### download

Download a file from the workspace to the local filesystem.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --output <out_path> | text | — | Output file path (default: same as filename). |
| --revision <revision> | text | — | Download file at specific revision. |

Exit codes: 0 — completed

### edit

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --force | boolean | — | Force-edit a calculated cell (override formula). |
| --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 '[batch-edit] Item[Ctx]'. 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'. Rejected with --replace, which takes a single undivided commit message. |
| --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. |

Exit codes: 0 — completed · 1 — partial

### example

Complete, valid documents to copy the shape from.

```bash
deepcell example
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --pack <pack> | text | — | Core examples plus this pack's. |

Exit codes: 0 — completed

### example get

Write an example document to a local file.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --into <into> | file | required | Local path to write the document to. |
| --layer <layer> | skeleton \| full | full | Which document to seed from. |
| --force | boolean | — | Overwrite an existing file. |

Exit codes: 0 — completed

### example list

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

```bash
deepcell example list
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --pack <pack> | text | — | Core examples plus this pack's. |

Exit codes: 0 — completed

### example show

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

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

Exit codes: 0 — completed

### grep

Search for items/values matching a pattern in .deepcell files.

deepcell grep <pattern>
```bash
deepcell grep Revenue
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --file <filename> | text | — | Search within a specific file. |
| --ignore-case | boolean | — | Case-insensitive search. |

Exit codes: 0 — completed

### guide

Explain how DeepCell itself works.

deepcell guide [topic]
```bash
deepcell guide orient/start
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --stage <stage> | text | — | Only this stage's topics (e.g. generate). |
| --pack <pack> | text | — | Only this domain pack's topics (e.g. finance). |
| --packs | boolean | — | List the domain packs. |
| --all | boolean | — | Include the legacy flat topics. |
| --search <search> | text | — | Topics whose name or description matches, across both catalogs. |

Exit codes: 0 — completed

### help

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

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

Exit codes: 0 — completed

### 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"}]'
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --items <items> | text | required | Items JSON string or path to JSON file. |
| --contexts <contexts> | text | required | Contexts JSON string or path to JSON file. |
| --name <name> | text | — | Name for the .deepcell file (default: input filename). |
| --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. |

Exit codes: 0 — completed · 1 — partial

### ingest cn extract

Extract one statement's table — rows, canonical items, #page deep link.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --statement <statement> | text | 合并利润表 | Chinese heading or income \| balance \| cash_flow |
| --persist | boolean | — | Mirror the source PDF into DeepCell storage and return a durable `source_page_url` to record as the <Source> <Locator>. --no-persist skips the mirror (faster, but the only url you get back is the volatile cninfo link). |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --type <filing_type> | text | annual | annual \| interim \| semiannual \| q1 \| q3 |
| --count <count> | integer range | 5 | number of reports (1-30) |

Exit codes: 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
```

Exit codes: 0 — completed

### ingest cn statements

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

```bash
deepcell ingest cn statements <pdf_url>
```

Exit codes: 0 — completed

### knowledge add

Add a new knowledge entry to a .deepcell file.

deepcell knowledge add <filename>
```bash
deepcell knowledge add model.deepcell
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --id <knowledge_id> | text | — | Unique knowledgeId (kebab-case) |
| --label <label> | text | — | Short title for the entry |
| --body <body> | text | — | Body text content |
| --ref <refs> | text | — | Cross-reference as item:<itemId> (repeatable) |
| --parent <parent> | text | — | Parent knowledgeId for hierarchy |
| --author <author> | agent \| human | — | Who is creating this entry |
| --level <level> | integer | — | (removed) not stored — use --parent for hierarchy |
| --from-json <from_json> | path | — | JSON file with an array of entries to add in bulk |
| --workspace <workspace_slug> | text | — | Override active workspace |

Exit codes: 0 — completed · 1 — written-but-invalid

### knowledge cat

Read a specific knowledge entry.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --workspace <workspace_slug> | text | — | Override active workspace |

Exit codes: 0 — completed

### knowledge delete

Delete knowledge entries from a .deepcell file.

deepcell knowledge delete <filename> [knowledge_ids...]
```bash
deepcell knowledge delete model.deepcell
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --yes | boolean | — | Skip confirmation prompt |
| --recursive | boolean | — | Delete entry and all descendants |
| --force | boolean | — | Force delete even if entry has children |
| --from-json <from_json> | path | — | JSON file with an array of IDs to delete |
| --workspace <workspace_slug> | text | — | Override active workspace |

Exit codes: 0 — completed · 1 — written-but-invalid

### knowledge list

List knowledge entries in a .deepcell file.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --flat | boolean | — | Flat list instead of tree view |
| --item-ref <item_ref> | text | — | Filter entries that reference this item |
| --author <author> | text | — | Filter by author (agent or human) |
| --parent <parent_id> | text | — | Filter by parent knowledgeId |
| --workspace <workspace_slug> | text | — | Override active workspace |

Exit codes: 0 — completed

### knowledge refs

Show cross-references for a knowledge entry.

deepcell knowledge refs <filename> <knowledge_id>
```bash
deepcell knowledge refs model.deepcell <knowledge_id>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --workspace <workspace_slug> | text | — | Override active workspace |

Exit codes: 0 — completed

### knowledge search

Search knowledge entries by text pattern (case-insensitive substring match on label and body).

deepcell knowledge search <filename> [pattern]
```bash
deepcell knowledge search model.deepcell
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --item-ref <item_ref> | text | — | Filter by item reference (entries that reference this item) |
| --workspace <workspace_slug> | text | — | Override active workspace |

Exit codes: 0 — completed

### knowledge search-all

Search knowledge entries across all accessible workspaces.

```bash
deepcell knowledge search-all <pattern>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --item-ref <item_ref> | text | — | Also filter by item reference |
| --workspace <workspace_slugs> | text | — | Limit to specific workspace(s) |
| --limit <limit> | integer range | 50 | Max results to return (1-1000). |
| --offset <offset> | integer range | 0 | Skip N results for pagination. |

Exit codes: 0 — completed

### knowledge update

Update an existing knowledge entry.

deepcell knowledge update <filename> [knowledge_id]
```bash
deepcell knowledge update model.deepcell
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --label <label> | text | — | New label text |
| --body <body> | text | — | New body text |
| --ref <refs> | text | — | Cross-reference as item:<itemId> (repeatable, replaces all refs) |
| --add-ref <add_refs> | text | — | Append a ref (item:<itemId>) without removing existing ones |
| --remove-ref <remove_refs> | text | — | Remove a ref (type:target) from existing ones |
| --parent <parent> | text | — | New parent knowledgeId |
| --author <author> | agent \| human | — | Who is updating this entry |
| --level <level> | integer | — | (removed) not stored — use --parent for hierarchy |
| --from-json <from_json> | path | — | JSON file with an array of entries to update in bulk |
| --workspace <workspace_slug> | text | — | Override active workspace |

Exit codes: 0 — completed · 1 — written-but-invalid

### log

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

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --file <filename> | text | — | Filter by filename. |
| --limit <limit> | integer | 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. |

Exit codes: 0 — completed

### login

Authenticate with the DeepCell API.

```bash
deepcell login
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --email <email> | text | — | Email for direct login (headless/CI). |
| --password <password> | text | — | Password for direct login (headless/CI). |

Exit codes: 0 — completed

### logout

Log out and remove stored credentials.

```bash
deepcell logout
```

Exit codes: 0 — completed

### ls

List files in the active workspace.

```bash
deepcell ls
```

Exit codes: 0 — completed

### merge apply

Apply conflict resolutions to a pending merge session.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --resolve <strategy> | ours \| theirs | required | Resolution strategy for all conflicts. |
| --file <filename> | text | — | Write merged result to this local file. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --base <base_rev> | text | — | Base revision SHA (defaults to last_sync_sha). |
| --theirs-rev <theirs_rev> | text | — | Revision for theirs (defaults to HEAD). |

Exit codes: 0 — completed · 1 — conflict

### merge resolve

Resolve a sync conflict for a .deepcell file.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --ours | text | — | Resolve all conflicts with local values. |
| --theirs | text | — | Resolve all conflicts with remote values. |

Exit codes: 0 — completed · 1 — conflict

### pull

Fetch latest cloud changes to the local folder.

```bash
deepcell pull
```

Exit codes: 0 — completed · 1 — conflict

### push

Upload local changes to the cloud workspace.

```bash
deepcell push
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --message <message> | text | "" | Commit message for the push. |

Exit codes: 0 — completed · 1 — written-but-invalid

### query

Query a .deepcell file.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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'. |
| --sheet <sheet_id> | text | — | Render a full sheet as markdown table. |
| --block <block_id> | text | — | Render a specific block within a sheet. |
| --workspace <workspace_slug> | text | — | Override active workspace. |

Exit codes: 0 — completed

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --from-id <from_id> | text | required | Source node id. |
| --to-id <to_id> | text | required | Target node id. |
| --rel <rel> | supports \| refutes \| depends_on \| derives_from \| variant_of \| supersedes \| contradicts \| references | required | 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), variant_of (your view vs a consensus claim), supersedes (replaces an older node), contradicts, references. See `deepcell guide reasoning`. |
| --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. |
| --status <status> | text | — | Argument lifecycle status (active/superseded/revoked). |

Exit codes: 0 — completed · 1 — written-but-invalid

### reasoning add-assumption

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

deepcell reasoning add-assumption <filename> --id <assumption_id>
```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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --id <assumption_id> | text | required | New Assumption id. |
| --label <label> | text | — | <Label> text. |
| --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. |
| --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 | — | CalcDef id anchoring this assumption to a formula in the model. |
| --item-refs <item_refs> | text | — | Comma-separated item ids the assumption constrains. Without it the unanchored_assumption lint warns — the assumption cannot be impact-traced or falsified when actuals drift in (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. |

Exit codes: 0 — completed · 1 — written-but-invalid

### reasoning add-claim

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

deepcell reasoning add-claim <filename> --id <claim_id> --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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --id <claim_id> | text | required | New Claim id. |
| --kind <kind> | thesis \| risk \| catalyst \| counter \| question \| market_consensus \| knowledge | required | What the claim is: thesis (what you conclude), risk / catalyst (what moves it, needs --probability), counter (the case against), question (open), market_consensus (someone else's view, needs --attribution), knowledge (a durable fact). See `deepcell guide reasoning`. |
| --label <label> | text | — | <Label> text. |
| --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. |
| --status-ref <status_ref> | text | — | Model Status dimension id (e.g. actual / projected) — NOT the claim lifecycle state (that is --status). Not permitted on --kind knowledge: knowledge claims are timeless (lint: status_ref_on_knowledge, error). |
| --calc-ref <calc_ref> | text | — | CalcDef id anchoring this claim to a formula in the model. |
| --item-refs <item_refs> | text | — | Comma-separated item ids anchoring this claim to the model. thesis/risk/catalyst claims need --item-refs or --calc-ref, else the unanchored_claim lint warns (they become invisible to reasoning-diff and item-scoped queries). question/knowledge/market_consensus are 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. |
| --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'. |
| --status <status> | draft \| active \| superseded \| falsified \| revoked | — | Claim lifecycle state — NOT the model's Status dimension (that is --status-ref). |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --id <evidence_id> | text | required | New Evidence id. |
| --source-ref <source_ref> | text | required | sourceId of a <Source> in <SourceDefinitions>. |
| --excerpt <excerpt> | text | — | <Excerpt> text. |
| --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). |
| --reliability <reliability> | text | — | primary \| secondary \| tertiary. |
| --effective-date <effective_date> | text | — | ISO8601 date. |
| --retrieved-at <retrieved_at> | text | — | ISO8601 date. |

Exit codes: 0 — completed · 1 — written-but-invalid

### reasoning delete-argument

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

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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 — an Argument's @id is optional, so a dangling edge cannot reliably be found and cleaned up later. |
| --allow-dangling | boolean | — | With --no-cascade, permit the delete even though it orphans Arguments. |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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 — an Argument's @id is optional, so a dangling edge cannot reliably be found and cleaned up later. |
| --allow-dangling | boolean | — | With --no-cascade, permit the delete even though it orphans Arguments. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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 — an Argument's @id is optional, so a dangling edge cannot reliably be found and cleaned up later. |
| --allow-dangling | boolean | — | With --no-cascade, permit the delete even though it orphans Arguments. |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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 — an Argument's @id is optional, so a dangling edge cannot reliably be found and cleaned up later. |
| --allow-dangling | boolean | — | With --no-cascade, permit the delete even though it orphans Arguments. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --syntax <graph_syntax> | mermaid \| dot | mermaid | Graph syntax to emit. Use the global -f json for the raw graph payload. |

Exit codes: 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
```

Exit codes: 0 — completed

### reasoning lint

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

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --strict | boolean | — | Exit non-zero on warn-level findings too (default: only error-level findings fail). |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --clear | boolean | — | Remove the declaration and fall back to deriving the apex from the argument topology. |

Exit codes: 0 — completed · 1 — written-but-invalid

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --id <new_id> | text | required | Id of the replacement Assumption. |
| --label <label> | text | — | <Label> text of the replacement. |
| --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. |
| --item-refs <item_refs> | text | — | Comma-separated item ids. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --id <new_id> | text | required | Id of the replacement Claim. |
| --label <label> | text | — | <Label> text of the replacement. |
| --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. |
| --kind <kind> | thesis \| risk \| catalyst \| counter \| question \| market_consensus \| knowledge | — | Kind of the replacement (defaults to the superseded claim's kind). |
| --item-refs <item_refs> | text | — | Comma-separated item ids. |
| --context-refs <context_refs> | text | — | Comma-separated context ids. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --rel <rel> | supports \| refutes \| depends_on \| derives_from \| variant_of \| supersedes \| contradicts \| references | — | 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. |
| --status <status> | text | — | Argument lifecycle status (active / superseded / revoked). |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --label <label> | text | — | Replacement <Label> text. |
| --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. |
| --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 | — | CalcDef id anchoring this assumption to a formula in the model. |
| --item-refs <item_refs> | text | — | Comma-separated item ids the assumption constrains — the cheap fix for an unanchored_assumption lint warning. |
| --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. |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --kind <kind> | thesis \| risk \| catalyst \| counter \| question \| market_consensus \| knowledge | — | Reclassify the claim — see `deepcell reasoning add-claim --help` for what each kind means. |
| --label <label> | text | — | Replacement <Label> text. |
| --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. |
| --status-ref <status_ref> | text | — | Model Status dimension id (e.g. actual / projected) — NOT the claim lifecycle state (that is --status). Not permitted on --kind knowledge: knowledge claims are timeless (lint: status_ref_on_knowledge, error). |
| --calc-ref <calc_ref> | text | — | CalcDef id anchoring this claim to a formula in the model. |
| --item-refs <item_refs> | text | — | Comma-separated item ids anchoring this claim to the model — the cheap fix for an unanchored_claim lint warning. |
| --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. |
| --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). |
| --status <status> | draft \| active \| superseded \| falsified \| revoked | — | Claim lifecycle state — NOT the model's Status dimension (that is --status-ref). |

Exit codes: 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>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --label <label> | text | — | Replacement <Label> text. |
| --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. |
| --source <source> | text | — | Replacement @source (where the evidence came from). |
| --url <url> | text | — | Replacement @url. |
| --as-of <as_of> | text | — | Replacement @asOf date (ISO). |
| --item-refs <item_refs> | text | — | Comma-separated item ids. |
| --context-refs <context_refs> | text | — | Comma-separated context ids. |

Exit codes: 0 — completed · 1 — written-but-invalid

### reasoning-diff

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

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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. |

Exit codes: 0 — completed · 1 — read-only-check · 2 — unparseable-document

### ref

Look up legal values, and resolve any typed id.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --limit <limit> | integer | 40 | Maximum search results. |

Exit codes: 0 — completed

### register

Create a new DeepCell account (headless/CI).

```bash
deepcell register
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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). |

Exit codes: 0 — completed

### relationships

Show the relationship graph of a .deepcell file.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --type <graph_type> | items \| dependencies \| blocks \| business \| unified | unified | Graph type. 'business' is the Item-centric Relationships workspace. |

Exit codes: 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>"
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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. |
| --message <commit_message> | text | — | Git commit message for the write. |
| --workspace <workspace_slug> | text | — | Override active workspace. |

Exit codes: 0 — completed · 1 — written-but-invalid

### restore

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

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --file <filename> | text | — | Restore specific file only. |
| --yes | boolean | — | Skip confirmation prompt. |

Exit codes: 0 — completed

### rm

Delete a file from the workspace.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --yes | boolean | — | Skip confirmation prompt. |

Exit codes: 0 — completed

### rules

The non-negotiable invariants every .deepcell model must satisfy.

deepcell rules [rule_id]
```bash
deepcell rules R2
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --pack <pack> | text | — | Restrict to the core rules plus this pack's (e.g. finance). |
| --full | boolean | — | Print every rule in full, not just the index — one call, every invariant, no per-rule round trips. |

Exit codes: 0 — completed

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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 server default (90 days, or 7 for a password-less --permission edit link and for anonymous sessions). Larger values are clamped to that cap. |
| --password <password> | text | — | Password-protect the link (account required). |
| --label <label> | text | — | Label to recognize the link in `share list`. |

Exit codes: 0 — completed

### share list

List active share links in the workspace.

```bash
deepcell share list
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --file <filename> | text | — | Only links for this file. |

Exit codes: 0 — completed

### share revoke

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

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

Exit codes: 0 — completed

### status

Show local changes vs last sync.

```bash
deepcell status
```

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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 .xlsx / .pptx exports written alongside this one. |

Exit codes: 0 — completed

### to-excel

Export a .deepcell file to Excel format.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --output <out_path> | text | — | Output file path (default: <filename>.xlsx). |
| --formulas | boolean | — | Export with live Excel formulas. |
| --recalculate | boolean | — | Recompute formula values via the LibreOffice service (requires --formulas). |
| --scenario <scenario_id> | text | — | Document scenario ID to export (applies its VariableOverrides; omit for the default scenario). |
| --variant <variant_id> | text | — | (removed) Never worked — see --scenario for document scenarios. |

Exit codes: 0 — completed

### to-pdf

Export a deck or a document as a PDF.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --from <source> | deck \| doc | deck | Which surface to render: the presentation deck, or the prose document. |
| --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. |
| --output <out_path> | text | — | Output path (default: <filename>_<deck\|doc>.pdf). |

Exit codes: 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
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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). |

Exit codes: 0 — completed

### upgrade

Check whether a newer deepcell CLI has been published.

```bash
deepcell upgrade
```

Exit codes: 0 — completed

### upgrade check

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

```bash
deepcell upgrade check
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --timeout <timeout> | float | 3 | How long to wait for each package index. |

Exit codes: 0 — completed

### upgrade disable

Turn the automatic upgrade check off.

```bash
deepcell upgrade disable
```

Exit codes: 0 — completed

### upgrade enable

Turn the automatic upgrade check on (the default).

```bash
deepcell upgrade enable
```

Exit codes: 0 — completed

### upgrade status

Show the setting and the last cached answer.

```bash
deepcell upgrade status
```

Exit codes: 0 — completed

### variant checkout

Check out a variant branch for local edits.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --main | boolean | — | Switch back to the main branch (clear active variant). |

Exit codes: 0 — completed

### variant create

Create a new variant branch.

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

Exit codes: 0 — completed

### variant diff

Show diff between a variant branch and main.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --file <file_path> | text | — | Limit the diff to a single file. |

Exit codes: 0 — completed

### variant list

List variants in the workspace.

```bash
deepcell variant list
```

Exit codes: 0 — completed

### variant merge

Merge a variant branch back into main.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --resolve <resolve> | ours \| theirs | — | Conflict resolution strategy: 'ours' keeps main, 'theirs' keeps variant. |

Exit codes: 0 — completed · 1 — conflict

### verify-email

Verify your email address.

```bash
deepcell verify-email
```

Exit codes: 0 — completed

### viewer

Print the browser URL to open FILENAME in the web workbench.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --workspace <workspace_slug> | text | — | Override active workspace. |
| --open | boolean | — | Open the URL in the default browser. |

Exit codes: 0 — completed

### whoami

Show the currently authenticated user.

```bash
deepcell whoami
```

Exit codes: 0 — completed

### workspace create

Create a new workspace.

```bash
deepcell workspace create <name>
```

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --slug <slug> | text | — | URL-friendly slug (auto-generated from name if omitted). |
| --description <description> | text | "" | Workspace description. |

Exit codes: 0 — completed

### workspace info

Show workspace details.

deepcell workspace info [slug]
```bash
deepcell workspace info
```

Exit codes: 0 — completed

### workspace list

List workspaces you belong to.

```bash
deepcell workspace list
```

Exit codes: 0 — completed

### workspace use

Set the active workspace for subsequent commands.

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

Exit codes: 0 — completed

### write

Create a file, or replace an existing one wholesale.

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

| Flag | Type | Default | What it does |
| --- | --- | --- | --- |
| --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. |
| --message <message> | text | "" | Commit message. |
| --revision <revision> | text | — | Expected revision SHA for optimistic locking — the `Revision:` line `deepcell cat` prints on stderr. The write is refused with a conflict if FILENAME changed since (a change to a different file is not a conflict). |

Exit codes: 0 — completed · 1 — written-but-invalid

## The rules

The invariants every model must satisfy, each with a stable id that other surfaces cite. Where a rule has lint backing, the listed code is what prints when the rule is broken — which is what turns it from advice into something you can check. The rest are audited in review.

```bash
deepcell rules R2
```

| Rule | What it says | Enforced by | Lint code |
| --- | --- | --- | --- |
| rule:R1 | Native generation — Excel at the edges only | review | — |
| rule:R2 | Driver-based forecasts | lint | hardcoded_literal_in_calc |
| rule:R3 | One model per request — one file, 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 |
| rule:R8 | Reasoning is mandatory | lint | unanchored_claim, unanchored_assumption, exclusivity_assertion, body_itemrefs_mismatch |
| rule:R9 | Every model carries PresentationDefinitions | lint | unrendered_value |
| rule:R10 | A DCF carries a real FCF bridge | review | — |
| rule:R11 | Circular structures by deliberate convention — and seeded | review | — |
| rule:R12 | Assumptions are grounded | review | — |
| rule:R13 | Statuses and periods declare what they mean | lint | undeclared_status_archetype, undeclared_context_state |
| rule:R14 | The model states its conclusion | lint | missing_apex_recommendation, dangling_conclusion_ref |
| rule:R15 | Prose that asserts a value must link it | review | — |
| rule:R16 | An outward address lives in exactly one place | review | — |
| rule:R17 | A cross-surface reference is a deepcell: URI | review | — |

## Examples

Complete, valid documents to start from, each chosen for the mechanic it demonstrates rather than its industry. They are rebuilt from their own transcripts and linted in CI, so none of them is a stale snippet. Copy the line under one to seed a file with it.

| Example | The mechanic it shows | Domain |
| --- | --- | --- |
| finance/saas-dcf | the full three-statement + DCF loop | finance |
| ops/headcount-plan | items × contexts, drivers, and scenarios | HR / operations |
| 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 / clinical research |
| supply/inventory-plan | sensitivity blocks | logistics |

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

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

```bash
deepcell example get ops/headcount-plan --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 — cohort is a custom Dimension that slices every data row instead of doubling it, and measured sits beside pre-registered under one item id rather than under two. The readout itself ships as a <Document>: every number in the prose is a link, so re-running the trial's numbers rewrites the write-up.

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