Skip to main content
The Contexity CLI is your primary surface for project setup, inspection, and automation. This page covers every available command, grouped by purpose.
Use --project /path/to/project on any command when your terminal is not already inside the project directory.

​
Project Setup

Use these commands to initialize a project, attach it to Contexity, and bootstrap initial context so your agent can orient itself from day one. 
contexity init --yes
contexity attach
contexity day0 --task "understand this project"
  • init --yes — Creates the .cxcap/ directory and writes a project.identity.json file, accepting all prompts automatically.
  • attach — Registers the current checkout with your local Contexity state home so subsequent commands know which project to operate on.
  • day0 --task — Runs a guided first-session bootstrap: it initializes, attaches, analyzes, and writes an opening context pack tailored to the task you describe.

​
Context

These commands manage the lifecycle of a working session — preparing context before you start, retrieving it mid-session, recording decisions, and closing out cleanly. 
contexity prepare --task "current work"
contexity resume --task "current work"
contexity capture decision --summary "Use cargo test before release."
contexity checkpoint --summary "Session complete."
  • prepare --task — Sets up a bounded context pack for an upcoming task. Run this before handing control to an agent so it starts with the right scope.
  • resume --task — Retrieves the current context pack for the named task. Use this to re-load context after an interruption or when continuing across sessions.
  • capture decision --summary — Records a new decision or note into the project context store. The summary is appended as a durable, retrievable fact.
  • checkpoint --summary — Records a session closeout. The checkpoint anchors the project’s state at this point so future sessions can resume cleanly.

​
Project Intelligence

These commands interrogate and refresh the project graph so Contexity can provide accurate impact analysis and routing information. 
contexity analyze --depth fast
contexity impact --path crates/contexity-app/src/lib.rs
contexity detect-changes --include-untracked
contexity route-map
  • analyze --depth — Refreshes the project graph. Use fast for a quick structural pass or full for a deeper traversal; run this after significant structural changes.
  • impact --path — Shows upstream and downstream impact for a specific file. Helps you understand what else in the project a change is likely to affect.
  • detect-changes --include-untracked — Maps all changed files (including untracked ones when the flag is set) through the project graph and reports their impact.
  • route-map — Lists all route surfaces discovered in the project, useful for navigating API or handler boundaries.

​
Host Setup

Use these commands to check which agent hosts are configured and to install Contexity’s MCP integration for a specific host. 
contexity host status
contexity host install codex --dry-run
contexity --yes host install codex
  • host status — Displays which host profiles are currently installed and whether their MCP configuration is active.
  • host install <profile> --dry-run — Previews the changes that would be made to a host’s configuration without applying them.
  • host install <profile> — Applies the MCP configuration for the chosen host profile. Pass --yes before host to skip confirmation prompts.
Supported host profiles: codex, claude-code, cursor, vscode.

​
Import and Export

Use these commands to move context capsules between machines or share a snapshot of project context with a teammate. 
contexity export --task "billing work"
contexity export --item "item-id"
contexity import /path/to/capsule --preview
contexity import /path/to/capsule --apply --only-safe
contexity import /path/to/capsule --apply --include-needs-review
  • export --task — Packages all context associated with a named task into a portable capsule file.
  • export --item — Packages a single context item by ID into a portable capsule file.
  • import --preview — Shows what a capsule contains and what it would change without writing anything.
  • import --apply --only-safe — Applies the capsule, skipping any items that would overwrite local state that Contexity cannot safely merge.
  • import --apply --include-needs-review — Applies the capsule including items flagged as needing review, so you can inspect and accept them manually.

​
Health and Value

Use these commands to check the quality of your project’s context, understand what Contexity has saved you, and run a comprehensive health report. 
contexity health --issues
contexity health --items
contexity value
contexity doctor
  • health --issues — Shows freshness and intelligence issues: stale context, missing analyses, or gaps in coverage.
  • health --items — Lists the individual context items associated with the current project, including their status and age.
  • value — Displays estimates of tokens saved and time recovered since Contexity was attached to the project.
  • doctor — Runs a full project health report, combining all intelligence, freshness, and configuration checks into a single diagnostic output.

​
Metrics Display

Use these commands to inspect and control whether Contexity surfaces usage metrics in your terminal after each agent run. 
contexity metrics status
contexity metrics disable
contexity metrics enable
  • metrics status — Shows the current metrics display policy (enabled or disabled).
  • metrics disable — Turns off post-run metrics output.
  • metrics enable — Turns metrics output back on.

​
MCP Server

Use this command to start the Contexity MCP server so an agent host can connect to it over standard I/O. 
contexity mcp serve --transport stdio
  • mcp serve --transport stdio — Starts the MCP server using standard input/output as the transport. Configure your host to launch this command and communicate over stdio.