Metadata-Version: 2.4
Name: deepcell-cli
Version: 0.6.1
Summary: Build and revise .deepcell documents from a terminal — the reasoning, the calculations, the document and the deck, with the links between them
Author-email: DeepCell <hello@deepcell.net>
License-Expression: MIT
Project-URL: Homepage, https://deepcell.net
Project-URL: Documentation, https://deepcell.net/product/cli
Keywords: deepcell,cli,financial-modeling,business-intelligence
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.28
Requires-Dist: rich>=13.0
Requires-Dist: mcp<2,>=1.26
Requires-Dist: pyjwt>=2.8
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: respx>=0.22; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: jsonschema>=4.20; extra == "dev"

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

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

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

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

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

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

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

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

```bash
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`).

```bash
# 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` |
| Sync | `clone`, `status`, `pull`, `push`, `commit`, `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:

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

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

```bash
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 guide revise/history`.

## Import & export

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

```bash
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://beta.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.
