CLI reference

One binary. The default command is the MCP server itself; everything else is tooling around it. All diagnostics go to stderr; stdout is reserved for MCP JSON-RPC (default command), listings, or the export payload (export --stdout).

ctxfile (default: the MCP server)

ctxfile [--root <dir>] [--config <path>]

Starts the stdio MCP server. Your client (Claude Code, Cursor, Claude Desktop) spawns this process, talks JSON-RPC over stdin/stdout, and stops it when done. Nothing listens on the network. See MCP surface for what it exposes.

ctxfile init / pause / resume

ctxfile init              # consent prompt, then installs the behavior pack per detected harness
ctxfile init --yes        # non-interactive consent
ctxfile init --no-auto    # record that auto-capture stays off
ctxfile init --uninstall  # reverse init: remove the behavior files + consent
ctxfile init --print <h>  # print one render: claude-code|cursor|agents-md|codex|generic
ctxfile pause             # refuse all automatic checkpoints (manual saves unaffected)
ctxfile resume            # re-enable

The Behavior Layer: agents checkpoint on their own, announced every time. ctxfile threads private <id> excludes a single thread from auto-capture.

ctxfile serve (Pro)

ctxfile serve [--port <n>] [--host <h>] [--root <dir>] [--config <path>]

Flag	Default	Effect
--port	4949 (or `serve.port`)	Port for the Streamable HTTP endpoint at `/mcp`.
--host	127.0.0.1 (or `serve.host`)	Bind address. Anything beyond loopback is refused unless `serve.tokens` is configured.

The HTTP door: the same five core tools over Streamable HTTP, one MCP session per client, each session bound to the bearer token that opened it. Tokens are named env vars with read:context/write:sessions scopes; without tokens the server is loopback-only and DNS-rebinding-protected. Pro tools stay on stdio. See Sync & roaming for the config shape and where this door leads.

ctxfile ui

ctxfile ui [--port <n>] [--no-open] [--root <dir>] [--config <path>]

Flag	Default	Effect
--port	4747	Dashboard port; if busy, the next 10 ports are tried automatically.
--no-open	off	Print the URL instead of opening the browser.

The server binds to 127.0.0.1 only and prints a URL carrying a one-time access token in the fragment (#token=...), which never appears in HTTP requests or logs. See Dashboard.

ctxfile export

ctxfile export [--profile repo-safe|full|custom] [--stdout] [--root <dir>] [--config <path>]

Flag	Default	Effect
--profile	repo-safe (or `export.profile` from config)	Redaction profile. `full` prints a loud warning; `custom` uses the `export.include` allowlist.
--stdout	off	Write the JSON envelope to stdout for piping, instead of `.ctxfile/context.{json,md}`.

Export always rebuilds the snapshot first; it never serves a cached one, so the artifact reflects the working tree as it is now. Details and the file format: Cloud agents and the .ctxfile convention.

ctxfile hooks

ctxfile hooks install     # add the managed pre-commit block
ctxfile hooks uninstall   # remove it

Installs a managed block in .git/hooks/pre-commit that regenerates the repo-safe export and stages it, so every commit carries fresh context. It is idempotent (reinstalling updates the block in place), appends politely to a hook you already have, and is guarded so a failed export never blocks a commit. Worktrees and custom core.hooksPath setups are resolved through git itself.

ctxfile ingest

ctxfile ingest list       # this project's agent-reported sessions
ctxfile ingest rm <id>    # delete one record by its listed id

Reviews what agents pushed through ingest_context or save_session: id, harness, session id, revision, last update, thread (when attached), and the summary head. Provenance and the full flow: Agent-assisted sessions.

ctxfile threads

ctxfile threads           # id, title, session count, last active, last surface

The durable work identities sessions attach to, most recently active first. Threads are created by saving a session with a thread name; there is deliberately no create/delete ceremony here. See Threads & handoff.

ctxfile activate

ctxfile activate <license-key>

Stores a Pro license key under ~/.ctxfile/. The Ed25519 signature is verified locally when the server starts; there is no activation server and no network call. See Pro.

Global flags

Flag	Default	Effect
--root <dir>	current directory	Project root to snapshot. All file access is scoped to it.
--config <path>	<root>/.ctxfile.json	Explicit config file location.
--version, -v		Print the version and exit.
--help, -h		Print usage and exit.

Environment variables

Variable	Role
NOTION_TOKEN	Notion integration token; activates the Notion connector together with `notion.pageIds`.
OLLAMA_BASE_URL	Overrides `ollama.baseUrl` (default `http://localhost:11434`).
Consult API keys	Read from whichever env vars you name in `consult.providers[].apiKeyEnv`. Keys never live in config files.

Exit behavior

Errors print a single ctxfile: ... line to stderr and exit non-zero. The default command runs until the client closes stdio.