CLI reference

The codifix CLI is the primary automation surface for Codifix. It configures projects, runs the backend, captures work, curates memory, answers questions, manages embeddings, opens the TUI, exposes MCP, and runs evaluations.

Use command help as the final source of truth before scripting:

codifix --help
codifix <command> --help
codifix <command> <subcommand> --help

Global options

Option	Env var	Purpose
`--config <path>`	`CODIFIX_CONFIG`	Use a specific global config file.
`--area <name>`	`CODIFIX_AREA`	Select an operator-configured knowledge area.
`--area-routing <path>`	`CODIFIX_AREA_ROUTING`	Use an operator-owned area routing policy, outside repositories.
`--writer-id <id>`	`CODIFIX_WRITER_ID`	Override the advisory writer label for captures and activity; authenticated principal identity is authoritative.
`--agent-id <id>`	`CODIFIX_WRITER_ID`	Alias for `--writer-id`; it changes the label, not authorization.

Many commands also support --project <slug>, --json, or --dry-run. Prefer --json for agent automation and --dry-run before commands that write config, memory, history, embeddings, or repo metadata.

Command shape

Most commands follow one of three shapes:

Shape	Example	Notes
Root command with flags	`codifix query --project memory --question "..."`	Common for query, scan, remember, status, doctor.
Command group with subcommand	`codifix commits sync --project memory`	Common for service, watcher, repo, graph, bundle, eval, embeddings, checkpoint.
Foreground long-running command	`codifix service run`	Runs until interrupted; use service managers for packaged background operation.

Command inventory

Current command inventory

This reference is checked against the CLI's visible root commands in Rust tests. Use command help for flags and subcommands.

Workflow	Commands	Use when
Start and set up	wizard, init, demo, tour	Configure Codifix, bootstrap a project, and try a guided example.
Use every day	remember, query, resume, tui	Capture finished work, ask cited questions, recover context, and inspect memory.
Diagnose	status, urls, health, doctor	Check the service, project configuration, and environment health.
Capture and curate	capture, curate, scan, ingest, proposals, consolidate, structure, review, archive	Collect evidence, make it durable, and review changes to canonical memory.
Reinforce and validate	scores, validate	Inspect what stays useful and validate it against project evidence.
History and sharing	history, prune-history, verify-provenance, bundle	Inspect versions, prove sources, keep history manageable, and transfer memory.
Workflow continuity	checkpoint, activities, up-to-speed	Record execution state and prepare the next person or agent to continue.
Project onboarding and sync	projects	Select approved projects, prepare workspaces and inspect synchronized knowledge.
Background jobs	jobs	Inspect durable enrichment and review failed-stage retries.
Supervisor	supervisor	Inspect instance policy, budgets and separate project-private interactions.
Private federation	federation	Review publications, grants, synchronization and exact expertise questions.
Connect people and tools	service, auth, watcher, agent, loops, mcp, embeddings	Run the backend, manage access, connect agents, and operate integrations.
Index project evidence	commits, repo, graph	Import repository history and build code-aware retrieval evidence.
Maintain and evaluate	eval, upgrade	Measure memory quality and refresh repo-local integration files.

Show all 46 visible root commands

wizard · init · demo · tour · remember · query · resume · tui · status · urls · health · doctor · capture · curate · jobs · supervisor · scan · ingest · proposals · consolidate · structure · review · archive · scores · validate · history · prune-history · verify-provenance · bundle · checkpoint · activities · up-to-speed · service · auth · projects · federation · watcher · agent · loops · mcp · embeddings · commits · repo · graph · eval · upgrade

The hidden contributor utilities codifix completion and codifix dev remain documented in Setup and bootstrap. They are intentionally not part of the everyday root-command inventory above.

Agent contract

Agents should follow a repeatable command pattern:

Run codifix query before answering project-specific questions.
Run codifix resume after interruptions or context loss.
Use codifix checkpoint start-execution when beginning approved plans.
Use codifix remember after meaningful completed work.
Use codifix status, codifix doctor, and codifix health before blaming retrieval or the TUI.

Read/write guide

Kind	Mostly read-only	Writes local or service state
Setup	`completion`, most `dev` inspection	`wizard`, `init`, `upgrade`, some `dev` scaffolding
Service	`status`, `doctor`, `health`	`service enable`, `service disable`, `service restart-all`, `watcher flush`
Query	`query`, `resume`, `up-to-speed`, `activities`, `history`, `verify-provenance`	Query/activity logging may write audit events when the service is running.
Memory	`proposals list`, `scan --dry-run`	`remember`, `capture`, `curate`, `scan`, proposal approval/rejection, `archive`, `prune-history`
Reinforcement	`scores`, `review list`	`validate`, `review apply`, `review reject`
Evidence	`repo status`, `graph status`, `embeddings list`	commit sync, repo indexing, graph extraction, embedding reindex/reembed/prune, bundle import
Integrations	`mcp status`, watcher status, `loops list`, eval compare	watcher start/stop, loop settings/runs/approvals, MCP HTTP service config, eval run artifacts

Project resolution

Area routing first chooses the installation; the project slug scopes knowledge inside it. A project name is not a cross-area identity. Inspect the area and instance in status before writing. See Areas and projects and routing precedence.

Commands that operate on memory need a project slug. In normal repo-local use, the CLI can read .codifix/project.toml; in automation, pass --project <slug> explicitly so the command does not depend on the current working directory.

codifix query --project memory --question "What changed in the docs site?"
codifix status --project memory --json

Output contracts

Commands intended for automation prefer JSON output where supported. Usage mistakes, such as missing required flags, normally exit with code 2. Operational failures normally exit non-zero and include a human-readable error on stderr.

Use codifix status --project <slug> --json as the first broad diagnostic when command behavior looks wrong.

Use Setup and bootstrap for installation flows or Query and briefings for day-to-day agent use.