CLI Reference - Codanna

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

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

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)

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:

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; 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

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:

{"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:

{"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}}

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.

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

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 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 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:

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:

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

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.

See Unix Piping for JSON envelope schema details.

​Global Flags

​Commands

​Index Flags

​Retrieve Subcommands

​Retrieve Search Filters

​Dump

​MCP Tools

​MCP Flags

​MCP Test

​Serve Options

​Documents Subcommands

​Documents Flags

​Profile Subcommands

​Profile Install Flags

​Parse Flags

​Benchmark

​Key:Value Arguments

​Exit Codes

Global Flags

Commands

Index Flags

Retrieve Subcommands

Retrieve Search Filters

Dump

MCP Tools

MCP Flags

MCP Test

Serve Options

Documents Subcommands

Documents Flags

Profile Subcommands

Profile Install Flags

Parse Flags

Benchmark

Key:Value Arguments

Exit Codes