diffmode

Agent-drivable CLI for the Diffmode growth pipeline. Thin wrapper around the hosted /public/v1/* API: authenticate, submit a run, watch a job, retrieve manifest-shaped results.

Tell your agent

Use the diffmode CLI to generate a growth plan for my product.

Most LLM agents (Claude Code, Codex, Cursor) understand that sentence after you install the bundled skill (see Agent integration below). For one-off use, you can also run diffmode directly without an agent — it's a plain CLI.

Quick start

# 1. Authenticate (paste a PAT from https://diffmode.app/app/tokens)
npx diffmode@latest login --token dm_pat_…

# 2. Run the free-tier diagnostic (1 credit) for your product
diffmode run my-product --input founder.json

# 3. Watch the job until terminal
diffmode jobs watch <job_id>

# 4. Download outputs + emit a manifest
diffmode results my-product

# 5. Optionally unlock the full plan (2 credits via CLI)
diffmode unlock my-product

Top-up is browser-only by design — diffmode never prompts for a card or invokes Stripe. When you run out of credits, the CLI exits with code 8 and a message pointing to https://diffmode.app/app/billing?channel=cli (the CLI credit-packs view: Starter $20/10 cr · Builder $40/30 cr · Scale $99/100 cr).

Install

# Primary path — no install, always latest
npx diffmode@latest <command>

# Global install (power users)
npm i -g diffmode

Requires Node ≥ 20.

Commands overview

Command	What it does	Credits (CLI)
diffmode login / logout / whoami	PAT-based authentication	—
diffmode run <product>	Free-tier diagnostic	0
diffmode unlock <product>	Full plan (needs prior run)	2
diffmode workflow <product>	Cold-start full workflow	2
diffmode idea-eval <product>	Score ideas vs. founder context	1
diffmode smoke-test <product>	Quick tactic smoke-test	1
diffmode jobs list/status/watch/resume/cancel	Job lifecycle	—
diffmode results <product>	Download + manifest	—
diffmode account / billing balance / history	Read-only billing	—
diffmode limits	Credits + rate-limit policy	—
diffmode diagnostics from-url/validate	Founder-input helpers	—
diffmode skill show / skill install / skill uninstall	Agent skill installer	—
diffmode commands	Machine-readable manifest	—

The credit column above is informational. Actual cost is fetched live from the server via GET /billing/balance (the response includes a credit_costs matrix for the caller's channel). CLI callers (PAT-authenticated) pay materially less than web callers — a $199 / 15-credit pack runs ~7 full pipelines from the CLI vs 1 from the browser. The table above shows current CLI prices; web prices are higher (workflow/unlock=15, idea-eval=5).

Full per-command reference: skills/diffmode/references/commands.md.

Submit commands (run, workflow, unlock, idea-eval, smoke-test) do a pre-flight GET /billing/balance before posting and exit 8 if the wallet balance is below the module cost. Pass --no-preflight to skip it when the agent has already verified credits this turn. If the server's pricing table is unreachable, the CLI exits with code 11 (pricing_unavailable) instead of falling back to a stale local constant.

Exit codes

Code	Meaning
0	OK
1	Generic error
2	Usage error (bad flags, missing required input)
3	Network
4	Auth (invalid/revoked token)
5	Conflict (in-flight job for the same product)
6	Not found
7	Rate-limited (Retry-After)
8	Insufficient credits (top up via browser at https://diffmode.app/app/billing?channel=cli)
9	Server (5xx)
10	Interrupted but resumable (diffmode jobs resume)
11	Pricing config unavailable (server's credit_costs table unreachable)
130	SIGINT (Ctrl-C; never cancels the server-side job)

Full per-code recovery guidance: skills/diffmode/references/error-codes.md.

Agent integration

diffmode ships an Anthropic-format skill (SKILL.md), an AGENTS.md companion, an llms.txt, and a Cursor MDC rule — all generated from one source so they don't drift.

Install them into your agent's known location:

# Install into Claude Code, Codex, and Cursor (default)
diffmode skill install

# Or pick a target
diffmode skill install --target claude
diffmode skill install --target cursor

# Inspect what would happen first
diffmode skill install --dry-run
diffmode skill install --print-paths

Default destinations:

Target	Path
Claude Code	~/.claude/skills/diffmode/SKILL.md
Codex	~/.codex/skills/diffmode/SKILL.md
Cursor	~/.cursor/rules/diffmode.mdc

Override with the env vars DIFFMODE_SKILL_CLAUDE_PATH, DIFFMODE_SKILL_CODEX_PATH, DIFFMODE_SKILL_CURSOR_PATH.

To preview the skill text without installing: diffmode skill show.

To remove the installed skill:

# Uninstall from all three (default)
diffmode skill uninstall

# Or pick a target
diffmode skill uninstall --target claude

# Preview first
diffmode skill uninstall --dry-run

If you've hand-edited the installed file, uninstall reports needs-confirm and writes nothing. Pass --yes to remove anyway. Empty skills/diffmode/ parent directories are cleaned up automatically for Claude and Codex targets; the Cursor ~/.cursor/rules/ directory is left alone.

Configuration

diffmode reads configuration in this order:

1. Per-command flag (e.g., --token, --timeout, --profile)
2. Environment variable
3. Built-in defaults

A ~/.config/diffmode/config.json profile registry is planned for Phase 2; 0.1.0 only reads the env vars below.

Environment variables

Variable	Purpose	Default
DIFFMODE_TOKEN	PAT (overrides stored, beaten by --token)	—
DIFFMODE_API_BASE	API base URL	https://ai-cmo-api.onrender.com/public/v1
DIFFMODE_BILLING_URL	Billing redirect base URL (?channel=cli is appended automatically)	https://diffmode.app/app/billing
DIFFMODE_PROFILE	Active profile name (overridden by --profile)	default
DIFFMODE_SKILL_CLAUDE_PATH	Override Claude skill install target	~/.claude/skills/diffmode/SKILL.md
DIFFMODE_SKILL_CODEX_PATH	Override Codex skill install target	~/.codex/skills/diffmode/SKILL.md
DIFFMODE_SKILL_CURSOR_PATH	Override Cursor MDC install target	~/.cursor/rules/diffmode.mdc
NO_COLOR=1	Disable ANSI colors	—

The active profile is used as the keyring account name, so different profiles can hold independent PATs (diffmode --profile staging login …).

Tokens are stored separately in the OS keyring (keytar) — or in a mode-0600 fallback file with a one-time stderr warning when the keyring isn't available.

JSON output contract

Every command emits JSON when stdout is not a TTY (or when --json is set). The envelope is schema-versioned:

Cat-style exception: diffmode results --show <path> and diffmode skill show stream raw file/markdown contents to stdout by default so diffmode skill show > SKILL.md and `diffmode results

--show

out.mdwork as documented. Pass--jsonexplicitly to get the{path, contents}envelope on these two read-out commands; on--showthe envelope also carriestruncated: truewhen--max-tokens` clipped the body.

{ "schema_version": "1", "job_id": "…", "status": "running" }

Errors go to stderr with the same envelope shape:

{ "error": { "code": "auth", "message": "…", "retryable": false } }

For agent self-discovery, run diffmode commands — it dumps the full commander tree as a stable, machine-readable manifest.

Idempotency

Idempotency-Key is the agent's responsibility (matches gh / stripe conventions). Generate a UUIDv4 and pass --idempotency-key <uuid> on each submit (run, workflow, unlock, idea-eval, smoke-test). Same key + same user → same job_id back (no double-charge). The CLI never auto-generates the key.

Security

• The CLI never logs the Authorization header value, even with --verbose (redacted to Bearer ***).
• login reads a PAT from stdin or --token but never echoes it back.
• The mode-0600 credential file fallback is only used when the OS keyring is unavailable; the CLI prints a one-time stderr warning when it falls back.

Report security issues per SECURITY.md.

Releases

See CHANGELOG.md for the per-version history.

Contributing

See CONTRIBUTING.md.

License

Apache-2.0. See LICENSE and NOTICE.