> ## Documentation Index
> Fetch the complete documentation index at: https://cxity.kairaxis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contexity CLI Command Reference

> Complete reference for all Contexity CLI commands: project setup, context retrieval, project intelligence, host config, import/export, health, and metrics.

The Contexity CLI is your primary surface for project setup, inspection, and automation. This page covers every available command, grouped by purpose.

<Note>
  Use `--project /path/to/project` on any command when your terminal is not already inside the project directory.
</Note>

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

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.