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

# CLI Reference

> Commands, flags, and options

Codanna is a local code intelligence MCP server and CLI for AI coding agents. This is the complete reference for the command-line interface — global flags, commands, MCP tools, and exit codes.

## Global Flags

These flags work on every command:

| Flag | Description |
| :- | :- |
| `-c, --config <path>` | Path to custom settings.toml |
| `--info` | Show detailed loading information |
| `-h, --help` | Print help |
| `-V, --version` | Print version |

## Commands

| Command | Description | Example |
| :- | :- | :- |
| `codanna init` | Set up `.codanna` directory with configuration | `codanna init` |
| `codanna index [paths]` | Build searchable index from codebase | `codanna index src lib` |
| `codanna add-dir <path>` | Add folder to indexed paths | `codanna add-dir src` |
| `codanna remove-dir <path>` | Remove folder from indexed paths | `codanna remove-dir old-project` |
| `codanna list-dirs` | List configured indexed directories | `codanna list-dirs` |
| `codanna retrieve <subcommand>` | Query symbols and relationships | `codanna retrieve symbol Parser` |
| `codanna dump` | Stream the resolved graph as JSON Lines | `codanna dump --edges --relation calls` |
| `codanna mcp <tool>` | Execute MCP tools directly | `codanna mcp find_symbol main` |
| `codanna mcp-test` | Test MCP connection and list tools | `codanna mcp-test --tool find_symbol` |
| `codanna serve` | Start MCP server | `codanna serve --watch` |
| `codanna documents <subcommand>` | Manage document collections | `codanna documents search "auth flow"` |
| `codanna profile <subcommand>` | Manage workspace profiles | `codanna profile install claude` |
| `codanna config` | Display active settings | `codanna config` |
| `codanna parse <file>` | Output AST as JSONL | `codanna parse src/main.rs` |
| `codanna benchmark [language]` | Benchmark parser performance | `codanna benchmark rust` |

## Index Flags

| Flag | Description | Default |
| :- | :- | :- |
| `-f, --force` | Force re-indexing even if index exists | |
| `-t, --threads <N>` | Number of threads (overrides `indexing.parallelism` in config) | All CPU cores |
| `--no-progress` | Disable progress bars | Progress enabled |
| `--dry-run` | Preview what would be indexed without indexing | |
| `--max-files <N>` | Maximum number of files to index | |

<Warning>
  `--force` with CLI paths clears the entire index but only rebuilds the specified paths. Other configured paths are not rebuilt. Run `codanna index --force` without paths to rebuild everything.
</Warning>

## Retrieve Subcommands

| Subcommand | Description | Example |
| :- | :- | :- |
| `symbol <name>` | Find symbol by name or `symbol_id:ID` | `codanna retrieve symbol Parser` |
| `calls <name>` | Functions called by a function | `codanna retrieve calls symbol_id:1883` |
| `callers <name>` | Functions that call a function | `codanna retrieve callers process_file` |
| `implementations <name>` | Types that implement a trait | `codanna retrieve implementations LanguageParser` |
| `describe <name>` | Full details: signature, docs, relationships | `codanna retrieve describe SimpleIndexer` |
| `search <query>` | Full-text search with filters | `codanna retrieve search "config" --kind function` |

All retrieve subcommands support:

* `--json` for JSON output
* `--fields <fields>` to filter JSON output to specific data fields
* `lang:<language>` filter (e.g., `lang:rust`)

### Retrieve Search Filters

| Flag | Description | Example |
| :- | :- | :- |
| `-l, --limit <N>` | Maximum number of results | `--limit 20` |
| `-k, --kind <kind>` | Filter by symbol kind | `--kind function` |
| `-m, --module <path>` | Filter by module path | `--module crate::parsing` |

Filters also work as key:value pairs:

```bash theme={null}
codanna retrieve search query:parse limit:5 kind:function
```

## Dump

Stream the whole index as JSON Lines: a `begin` envelope, one `result` envelope per symbol and per relationship, and a terminal `summary` envelope. Every line is the standard [JSON envelope](/workflows/piping); row ordering is unspecified. Available since v0.14.0.

| Flag | Description |
| :- | :- |
| `--symbols` | Emit symbol rows only |
| `--edges` | Emit relationship rows only |
| `--relation <kind>` | Keep relationship rows of one kind: `calls`, `defines`, `uses`, `implements`, `extends` |
| `--kind <kind>` | Keep symbol rows of one kind (`function`, `method`, `struct`, ...); relationship rows are unaffected |

```bash theme={null}
codanna dump > graph.jsonl
codanna dump | jq -c 'select(.type=="result") | .data'
codanna dump --edges --relation calls
codanna dump --symbols --kind method
```

A relationship row identifies both endpoints by name, kind, file, and line, and carries the persisted call metadata:

```json theme={null}
{"type":"result","status":"success","code":"OK","exit_code":0,"message":"","data":{"relation":"Calls","from":{"id":5,"name":"test_target_function","kind":"Function","file_path":"tests/test_mod.py","line":4},"to":{"id":3,"name":"target_function","kind":"Function","file_path":"src/pkg/mod.py","line":1},"metadata":{"line":5,"column":11,"receiver":null,"static_call":false,"context":null}},"meta":{"schema_version":"1.0.0","entity_type":"relationship"}}
```

The `summary` envelope closes the stream with totals and index provenance:

```json theme={null}
{"type":"summary","status":"success","code":"OK","exit_code":0,"message":"dump complete","data":{"symbols":5,"relationships":1,"orphan_edges_dropped":0,"duplicate_symbol_ids":0,"emission_version":3,"builder_commit":"023afdc"},"meta":{"schema_version":"1.0.0","entity_type":"graph","count":6}}
```

<Note>
  Scalar `line` fields (endpoint `line`, metadata `line`) are 1-indexed editor coordinates; `range` objects on symbol rows are 0-indexed machine coordinates. `id` values are scoped to the current index instance and change across re-indexes — identify symbols durably by name, file, line, and kind.
</Note>

An unknown `--relation` or `--kind` value is rejected before any line is written (exit `2`, accepted values listed on stderr). A stale index refuses with exit `7` as on every read command.

## MCP Tools

| Tool | Description | Example |
| :- | :- | :- |
| `find_symbol` | Find symbol by exact name | `codanna mcp find_symbol main` |
| `search_symbols` | Full-text search with fuzzy matching | `codanna mcp search_symbols query:parse limit:10` |
| `semantic_search_docs` | Natural language search | `codanna mcp semantic_search_docs query:"error handling" limit:5` |
| `semantic_search_with_context` | Natural language search with relationships | `codanna mcp semantic_search_with_context query:"auth logic" limit:3` |
| `get_calls` | Functions called by a function | `codanna mcp get_calls symbol_id:567` |
| `find_callers` | Functions that call a function | `codanna mcp find_callers process_file` |
| `analyze_impact` | Impact radius of symbol changes | `codanna mcp analyze_impact Parser` |
| `search_documents` | Search indexed documents | `codanna mcp search_documents query:"setup guide" limit:5` |
| `get_index_info` | Index statistics | `codanna mcp get_index_info` |

See [Tool Tiers](/workflows/tool-tiers) for recommended usage patterns.

### MCP Flags

| Flag | Description |
| :- | :- |
| `--json` | Output in JSON format |
| `--fields <fields>` | Filter JSON output to specific data fields |
| `--watch` | Check for file changes and reindex before running the tool |
| `--args <json>` | Pass tool arguments as a JSON string |

## MCP Test

Test MCP server connectivity and tool execution:

| Flag | Description | Default |
| :- | :- | :- |
| `--tool <name>` | Tool to call (omit to list available tools) | |
| `--args <json>` | Tool arguments as JSON | |
| `--server-binary <path>` | Path to server binary | Current binary |
| `--delay <seconds>` | Wait before calling the tool | |

```bash theme={null}
codanna mcp-test
codanna mcp-test --tool find_symbol --args '{"name":"main"}'
```

## Serve Options

| Flag | Description | Default |
| :- | :- | :- |
| `--watch` | Enable hot-reload when index changes | |
| `--watch-interval <N>` | Seconds between change checks | 5 |
| `--http` | Enable HTTP server with OAuth | |
| `--https` | Enable HTTPS server with TLS | |
| `--bind <addr>` | Address to bind HTTP/HTTPS server | 127.0.0.1:8080 |

## Documents Subcommands

| Subcommand | Description | Example |
| :- | :- | :- |
| `add-collection <name> <path>` | Add document collection | `codanna documents add-collection docs docs/` |
| `remove-collection <name>` | Remove document collection | `codanna documents remove-collection docs` |
| `index` | Index collections | `codanna documents index` |
| `search <query>` | Search indexed documents | `codanna documents search "auth flow"` |
| `list` | List all collections | `codanna documents list` |
| `stats <name>` | Show collection statistics | `codanna documents stats docs` |

### Documents Flags

| Flag | Subcommands | Description |
| :- | :- | :- |
| `--collection <name>` | index, search | Filter to a specific collection |
| `--all` | index | Index all configured collections |
| `-f, --force` | index | Force re-indexing of all files |
| `--no-progress` | index | Disable progress bars |
| `-l, --limit <N>` | search | Maximum results to return |
| `-p, --pattern <glob>` | add-collection | Glob pattern for file matching (default: `**/*.md`) |
| `--json` | search, list, stats | Output in JSON format |
| `--fields <fields>` | search | Filter JSON output to specific data fields |

See [Document Search](/features/document-search) for details.

## Profile Subcommands

| Subcommand | Description | Example |
| :- | :- | :- |
| `init <name>` | Initialize project with a profile | `codanna profile init claude` |
| `install <name>` | Install profile to workspace | `codanna profile install claude` |
| `list` | List available profiles | `codanna profile list --verbose` |
| `status` | Show installed profiles | `codanna profile status` |
| `sync` | Install from team configuration | `codanna profile sync` |
| `update <name>` | Update installed profile | `codanna profile update claude` |
| `remove <name>` | Remove profile | `codanna profile remove claude` |
| `verify [name]` | Verify profile integrity | `codanna profile verify claude` |
| `provider add <source>` | Register provider | `codanna profile provider add bartolli/codanna-profiles` |
| `provider remove <id>` | Remove provider | `codanna profile provider remove codanna-profiles` |
| `provider list` | List registered providers | `codanna profile provider list --verbose` |

### Profile Install Flags

| Flag | Description |
| :- | :- |
| `--source <source>` | Profile source (git URL or local directory) |
| `--ref <ref>` | Git reference (branch, tag, or commit SHA) |
| `-f, --force` | Force installation even if profile exists |

See [Collaboration](/features/collaboration) for details.

## Parse Flags

| Flag | Description | Default |
| :- | :- | :- |
| `-o, --output <path>` | Output file | stdout |
| `-d, --max-depth <N>` | Maximum depth to traverse | |
| `-a, --all-nodes` | Include all nodes (default: named nodes only) | |

## Benchmark

Benchmark parser performance for one or all languages:

```bash theme={null}
codanna benchmark                  # All languages
codanna benchmark rust             # Single language
codanna benchmark --file src/lib.rs  # Custom file
```

Supported: rust, python, php, typescript, go, csharp, all.

## Key:Value Arguments

Retrieve, MCP, and documents commands accept arguments as key:value pairs:

```bash theme={null}
codanna retrieve search query:parse limit:5 kind:function
codanna mcp semantic_search_docs query:"error handling" limit:3 lang:rust
codanna documents search query:"auth" limit:5 collection:docs
```

This format is equivalent to using flags and works alongside them.

## Exit Codes

| Code | Meaning |
| :- | :- |
| `0` | Success with results |
| `1` | Not found (no results) |
| `2` | Error (invalid query, parse error, etc.) |

<Note>
  An index built by a binary with different output semantics is refused before any tool runs: read commands exit `7` with a message naming both versions, and `codanna index` rebuilds from scratch automatically. This prevents mixed-semantics results after an upgrade. The automatic rebuild also re-embeds when semantic search is enabled; large repositories take minutes. Since v0.10.1, a stale-index `codanna serve` (stdio) completes the MCP handshake with no tools and rebuild instructions, so MCP clients report the fix instead of a generic connection failure.
</Note>

See [Unix Piping](/workflows/piping) for JSON envelope schema details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.