CodeNavi — CLI Reference¶

codenavi is a command-line client for a running CodeNavi server: search, read, chat, reindex, and admin — straight from the terminal, no MCP client or browser needed. Read-query commands talk to the index directly; chat/reindex/status reuse the running server's loaded models.

Running it¶

Two equivalent ways:

# Host wrapper (recommended) — runs the command inside the container.
# Put the repo-root `codenavi` script on your PATH, or call it directly:
./codenavi search "how does payment work?"

# Inside the container:
docker exec -i codenavi python3 tools/cli.py search "how does payment work?"

The wrapper just runs docker exec -i <container> python3 tools/cli.py … for most commands, so the two forms are interchangeable — except crawl, which the wrapper execs directly against crawler.py, and bare chat (no message), which only opens an interactive session through the wrapper's own REPL loop.

Env var	Default	What it does
`CODENAVI_CONTAINER`	`codenavi`	Container name (set this if you renamed it)
`CODENAVI_PORT`	`8765`	Server port for `chat` / `reindex` / `status` HTTP calls
`CODENAVI_AUTH_TOKEN`	(none)	Bearer token — required for authenticated commands when the server has auth on

-v / --verbose prints retrieval metadata to stderr (chat only). Many commands take --codebase NAME to target one codebase (default: the server's default_codebase, falling back to all).

Search & read¶

Command	What it does	Key flags
`search "<query>"`	Semantic search across code, docs, and crawled web	`--limit` (5), `--source-type code\\|doc\\|web`
`file "<query>"`	Find files by name or path	`--limit` (5)
`grep <pattern>`	Regex search across files	`--path`, `--exclude`, `--language`, `--case-sensitive`, `--limit` (50, cap 200), `--context` (cap 5)
`symbol <name>`	Find a function/class/method (FTS, no GPU)	`--kind`, `--language`, `--path`, `--limit` (20), `--source`
`refs <name>`	Find references to a symbol	`--language`, `--path`, `--limit` (30)
`read <path>`	Read a file (line-numbered, secrets redacted)	`--start`, `--end`
`ls [path]`	Tree-style directory listing	`--depth` (2, cap 5)
`overview`	Structural overview (languages, dirs, symbols)	`--section`
`codebases`	List configured codebases with chunk counts
`index-stats`	Index statistics for a codebase	`--codebase`

Q&A¶

Command	What it does	Key flags
`chat "<message>"`	Grounded Q&A across code, docs & web (needs an LLM backend)	`--codebase`, `--trace`
`chat`	Start an interactive chat session

Indexing & admin¶

Command	What it does	Key flags
`init <path>`	Scan a codebase and generate a starter `settings.json`	`--output`, `--force`
`reindex`	Rebuild the search index	`--full`, `--codebase`
`reindex-status`	Poll a running reindex
`reindex-cancel`	Cancel a running background reindex
`reindex-compare`	Compare the current index to a backup	`--backup`, `--codebase`, `--list`
`claude-md`	Auto-generate a `CLAUDE.md` project summary	`--codebase`
`backup`	Snapshot LanceDB + SQLite + chat + settings
`restore <backup_id>`	Restore state from a snapshot
`reload-aliases`	Reload alias files from disk without a restart
`status`	Server health check
`version`	Print the server version

Docs¶

Command	What it does	Key flags
`docs-list`	List indexed documentation files with chunk counts	`--codebase`
`docs-reindex`	Re-ingest PDFs/DOCX from `DOCS_DIR`	`--codebase`

Feedback & analytics¶

Command	What it does	Key flags
`feedback-submit <query> <chunk_id> <source_file>`	Rate a search result	`--rating -1\\|1` (required), `--comment`
`feedback-stats`	Promoted/demoted chunk stats
`analytics`	Query analytics (top queries, zero-result, FTS)	`--since YYYY-MM-DD`, `--top` (10)

Crawler (opt-in)¶

Available when the crawler is enabled (CRAWLER_ENABLED=true).

Command	What it does	Key flags
`crawl <subcommand>`	Run the web crawler (run, status, …)
`runs`	List crawl runs	`--env`, `--limit` (10)
`run-summary`	Stats for a crawl run (latest if omitted)	`--run-id`
`runs-compare`	Diff two crawl runs (regressions vs fixes)
`errors <query>`	Search crawled errors
`urls <pattern>`	Find crawled pages by URL pattern
`referrers <url>`	Pages that link to a given URL
`crawl-cancel`	Stop a running crawl

Examples¶

codenavi status                                  # is the server healthy?
codenavi search "where are webhooks verified" --limit 8
codenavi search "rate limiting" --source-type code
codenavi symbol PaymentService --kind class --source
codenavi refs verifyCredentials
codenavi grep "TODO|FIXME" --language php --context 2
codenavi read src/app/Http/Kernel.php --start 1 --end 40
codenavi chat "explain the auth flow"            # one-shot Q&A
codenavi reindex --full --codebase laravel       # full rebuild of one codebase
codenavi analytics --since 2026-06-01 --top 20

For the equivalent MCP tools (same engine, called by your agent), see api-reference.md.