DeepCell CLI

Command-line interface for DeepCell — a versionable .deepcell document that records the reasoning, the calculations, the document and the deck together with the links between them, so when an assumption changes you can see which conclusions still hold. AI agents read and write the format natively; this CLI is the primary tool for doing so from a terminal, script, or agent harness.

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

# Windows (PowerShell)
irm https://deepcell.net/install.ps1 | iex

deepcell --help
deepcell-mcp --help           # MCP server (also included)

The installer picks uv or pip — whichever the machine has, fetching uv first if it has neither — finds where the console script actually landed, and adds that directory to your shell profiles so deepcell still resolves in the next shell. It handles the two cases a bare pip install does not: a stock Debian or Ubuntu image, which ships no pip, no ensurepip and no venv module, and a PEP 668 interpreter that refuses to install into itself. Running it twice is safe, and it verifies before reporting success.

Prefer to install by hand? deepcell-cli is on PyPI:

uv tool install deepcell-cli
uv tool update-shell

or pip install deepcell-cli.

deepcell: command not found after installing by hand means the console script landed in a directory that is off PATH — not that the install failed. Re-run the installer above, which fixes exactly that; or use python3 -m deepcell_cli (python -m on Windows), which is the same CLI with no PATH involved.

More generally, a bare deepcell failing is not "not installed". It means one of four things, and only one is fixed by installing: nothing is installed; a copy exists in a directory that is off PATH; a copy exists and the host — a sandbox, a policy — refuses to execute it; a copy exists, runs, and is behind. The installer tells them apart: it looks on PATH and where an install lands, runs what it finds by absolute path, keeps a current copy, upgrades an outdated one, puts an off-PATH one on PATH, and refuses to reinstall one the host will not run (reinstalling would not change that). Its last line on stderr is one a script reads — deepcell-install: state=<state> version=<version> dir=<directory> — where state is installed, upgraded, reinstalled, installed-current, installed-unknown (it runs; the package index could not be reached), installed-blocked (exit 3) or failed. An upgrade goes through the tool that owns the copy — uv when uv tool list names it, else pip. stdout is still just the directory. DEEPCELL_FORCE=1 is the repair path: reinstall even when current. On Windows, a PATH the installer writes reaches new sessions only; a host that is already running keeps its environment, so use the directory the installer returns:

$bin = irm https://deepcell.net/install.ps1 | iex
& (Join-Path $bin 'deepcell.exe') --version

Designed for agents

The CLI is built to be driven programmatically:

• Machine-readable output. Every command accepts -f json (also table, plain; default plain). Structured data goes to stdout, status/error messages to stderr, and failures exit non-zero — pipes and jq work cleanly:

  deepcell query model.deepcell Revenue FY2025E projected -f json | jq .value
  

• Headless auth. deepcell register creates an account without a browser; DEEPCELL_ACCESS_TOKEN injects a token for CI; DEEPCELL_CONFIG points at an alternate config file for session-scoped isolation.

• Non-interactive flags. Destructive commands accept -y; --project SLUG targets a project per-invocation without mutating global state.

• Built-in workflow guidance. deepcell guide lists the topics by workflow stage — orient/start, generate/calcs, revise/scenarios, verify/lint, present/decks, and the rest. Read one with deepcell guide <topic>, find one with deepcell guide --search <text>, and add the older flat topics with deepcell guide --all. When unsure how to model something, consult a guide topic before improvising.

Quick start

# 1. Authenticate — browser flow, or headless:
deepcell login
# deepcell register            # terminal-only account creation (CI/agents)

# 2. Create and activate a project
deepcell project create "My Project"
deepcell project use my-project

# 3. Work with files
deepcell ls                                               # list files
deepcell describe model.deepcell                          # inspect schema
deepcell query model.deepcell Revenue FY2025E projected   # query one value
deepcell query model.deepcell --sheet income_statement    # render a sheet
deepcell edit model.deepcell Revenue_Growth FY2025E 0.12  # edit an assumption
deepcell to-excel model.deepcell -o report.xlsx           # export to Excel

Value addressing

Every value is addressed by up to five dimensions:

Dimension	Role	Examples	If omitted
Item	what	Revenue, COGS, WACC	required
Context	time period	FY2025E, Q1_2024	all contexts
Status	actual vs. projected	actual, projected	all statuses
Scenario (--scenario)	what-if branch	bull, downside	default scenario
Custom dimensions (--custom-dimensions)	any extra axis	geography:na;segment:cloud	base cell

deepcell query model.deepcell Revenue FY2025E projected
deepcell query model.deepcell Revenue FY2025E --scenario bull
deepcell query model.deepcell Revenue FY2025E --custom-dimensions "geography:na"
deepcell cell-meta model.deepcell Revenue FY2025E    # formula, dependencies, provenance

The custom-dimension grammar is dim:member, semicolon-separated. Omitting a flag targets the base cell, never an error.

Editing: pick the right tool

You want to change…	Use	Why
A hardcoded input (assumption, historical)	deepcell edit FILE ITEM CTX VALUE	literal Values
A formula, item, period, scenario, sheet, format	deepcell defs <op>	structural, validated, atomic
A computed cell → hardcoded override	deepcell edit … --force	flags the override explicitly
A hardcoded cell → back to computed	deepcell edit FILE ITEM CTX --clear	lets the CalcDef re-govern it
Raw XML (last resort)	deepcell replace FILE OLD NEW	string replacement with lint

Derived metrics belong in a CalculationDefinition, not hardcoded values — the engine recomputes every CalcDef on read (deepcell guide generate/calcs).

# Batch value edits (JSON array via file, inline, or stdin)
deepcell edit model.deepcell --batch changes.json
echo '[{"itemRef":"Revenue","contextRef":"FY2025E","newValue":"1500000","statusRef":"projected"}]' \
  | deepcell edit model.deepcell --batch -

# Structural edits
deepcell defs add-item model.deepcell --name Gross_Profit --label "Gross Profit"
deepcell defs add-calc model.deepcell --item Gross_Profit \
  --formula "Revenue - COGS" --status projected --dry-run   # pre-flight, then re-run without --dry-run
deepcell defs add-scenario model.deepcell --name Bull
deepcell defs apply model.deepcell --ops ops.json     # many ops, atomically

deepcell defs --help lists the full op set: add-* / update-* / delete-* / rename-* / reorder-* for items, calcs, contexts/periods, scenarios, statuses, formats and rules, presentation blocks, and sensitivity tables, plus header for document metadata.

Command reference

Group	Commands
Auth	login, register, logout, whoami, verify-email, account
Projects	project list / use / create / info
Files	ls, cat, write, rm, download
Inspection	describe, query, cell-meta, relationships, grep, doctor
Editing	edit, defs, replace, variant checkout / create / diff / merge / list
Document surface	doc — outline, blocks, body, links, lint
Deck surface	deck — slides, ordering, binding, branding
Change review	changes list / diff / revert, impact
Version control	log, diff, restore, commit
Sync (people, not agents)	clone, status, pull, push, merge
Import / export	import, ingest, to-excel, to-docx, to-pptx, to-pdf
Reasoning	reasoning, reasoning-diff, claim, assumption
Delivery	viewer, share create / list / revoke
Knowledge	help, guide, rules, ref, example

Run deepcell <command> --help for detailed usage — the help text includes worked examples for every mode.

Reasoning

.deepcell files carry a typed reasoning graph — Claims, Assumptions, Evidence, connected by Argument edges — so a model explains why its numbers are what they are:

deepcell reasoning add-claim model.deepcell --id rev-thesis --kind thesis \
  --label "Revenue doubles by FY27" --item-refs Revenue
deepcell reasoning graph model.deepcell        # render as Mermaid
deepcell reasoning impact model.deepcell rev-thesis   # what depends on this claim?
deepcell reasoning lint model.deepcell         # structural checks
deepcell claim model.deepcell                  # inspect claims
deepcell assumption model.deepcell             # inspect assumptions

See deepcell guide revise/reasoning and deepcell guide verify/review.

Variants, history, and merge

deepcell variant create "Best Case"       # parallel assumption set, no file copies
deepcell variant checkout best-case
deepcell variant diff best-case           # vs main
deepcell variant merge best-case

deepcell log                              # like git log
deepcell diff abc123 def456               # compare two revisions
deepcell restore abc123                   # like git checkout

deepcell merge resolve model.deepcell     # semantic 3-way merge of sync conflicts
deepcell merge resolve model.deepcell --ours   # keep local values (--theirs: remote)

Sync (local ↔ cloud)

deepcell clone my-project              # download to ./my-project/
cd my-project
# ... edit files locally ...
deepcell status                          # A/M/D vs last sync
deepcell push -m "Updated assumptions"   # upload
deepcell pull                            # fetch cloud changes

A .deepcell/ metadata directory tracks the project link and sync state. push refuses to clobber cloud changes — it asks you to pull first. See deepcell help clone.

Sync moves bytes, not the commands that read them: query, describe --lint, cat and every other read address the project on the server, so inside a clone they answer from the cloud's HEAD and not from the file you just edited. push first, then read back. Sync is a human workflow for this reason and is unavailable over MCP.

Import & export

deepcell import revenue.xlsx --items items.json --contexts contexts.json \
  --aggregations aggregations.json --keep-raw
deepcell to-excel model.deepcell -o report.xlsx --formulas   # live Excel formulas
deepcell to-docx model.deepcell -o memo.docx                 # the document, as Word
deepcell to-pptx model.deepcell -o deck.pptx                 # HTML deck → editable PowerPoint
deepcell to-pdf model.deepcell -o memo.pdf                   # the document, as PDF
deepcell ingest cn ...                                        # A-share (cninfo) filings

--aggregations maps and combines source rows into target coordinates (SUM, AVERAGE, MIN, MAX, COUNT); --keep-raw retains originals alongside. See deepcell guide excel-import and deepcell guide schema-matching.

MCP server

The package ships deepcell-mcp, exposing the whole CLI to MCP clients (Claude Code, Claude.ai, and others) as a single deepcell(command) tool:

deepcell-mcp                      # stdio transport (local)
deepcell-mcp --http               # streamable-http on 127.0.0.1:8080

Interactive and sync commands (login, clone, push, …) are blocked inside MCP; authenticate with an API key or OAuth instead.

Environment variables

Variable	Purpose	Default
DEEPCELL_API_URL	API endpoint	https://deepcell.net/api/jingwei
DEEPCELL_PROJECT	Override active project	(none)
DEEPCELL_ACCESS_TOKEN	Auth token for CI/headless use	(none)
DEEPCELL_CONFIG	Alternate config.json path (session-scoped)	~/.deepcell/config.json
DEEPCELL_NO_ANON	Opt out of the anonymous first-use session	(unset)
DEEPCELL_NO_UPGRADE_CHECK	Silence the upgrade-available notice for this process	(unset)

Precedence: per-invocation flags (--project) > environment > ~/.deepcell/config.json. Credentials live in ~/.deepcell/credentials.json (0600); token refresh is automatic.

License

MIT. The CLI is developed in a private repository, so there is no public source link to follow from here — the licence is what ships in the package metadata.