CLI

The rce-code command-line interface is a thin wrapper over the Python facade. It is a Click command group: rce-code <command> [ARGS] [OPTIONS]. Every command opens (or creates) the index for the target repository, runs, prints plain-text results, and closes. This page documents every command, its arguments, and its options exactly as defined.

How the CLI locates the index

There is no global repository flag — instead, every command takes its own --repo option, which defaults to . (the current directory). The index database itself lives at <repo>/.rce/code/index.db and is opened (or created, with migrations applied) on each invocation. So running a command from inside a repository "just works"; from elsewhere, point it with --repo.

repo resolution

# Run from inside the repository (default --repo is ".")
rce-code index

# Or target a repository explicitly from anywhere
rce-code index --repo /path/to/repo

Index on first use

Like the Python facade, every CLI command calls open_or_create, so the .rce/code/index.db file and its schema are created on first use. Run rce-code index before any search command, and rce-code embed before the semantic and hybrid searches.

Commands

Command	What it does
`index`	Index (or refresh) the repository.
`stats`	Print index health for the repository.
`search`	Lexical (FTS5 BM25) search for a query.
`search-semantic`	Semantic (vector) search for a query — run `embed` first.
`search-hybrid`	Hybrid search fusing lexical + semantic + symbol results.
`grep`	Grep the repository via ripgrep.
`embed`	Embed chunks that lack a current embedding.
`symbols`	List symbol definitions in a file.
`find`	Find symbol definitions by name across the repo.
`refs`	Show references (calls + imports) to a name.
`callers`	Show resolved callers of the symbol(s) named.
`callees`	Show resolved callees of the symbol(s) named.
`repomap`	Print a relevance-ranked repository map within a token budget.

--repo is on every command

Each command below also accepts --repo <path> (default .). It is omitted from the per-command option tables to avoid repetition; assume it is always available.

index

Build or incrementally refresh the index. Idempotent — unchanged files are hash-skipped.

Argument / Option	Default	Description
`--repo`	`.`	Repository root.

Prints a one-line summary: indexed N file(s), deleted N, skipped {...}.

index

rce-code index --repo /path/to/repo

stats

Print index health: counts, embedding coverage, FTS status, and skip reasons.

Argument / Option	Default	Description
`--repo`	`.`	Repository root.

stats

$ rce-code stats
files: 128
chunks: 942
symbols: 1530
refs: 3104
embedding_coverage: 1.00
fts_ok: True
skipped: {'binary': 3, 'too_large': 1}

search

Lexical FTS5 BM25 search over indexed chunks.

Argument / Option	Default	Description
`QUERY` (positional)	—	The search query.
`-k`, `--top-k`	`10`	Maximum number of results.
`--repo`	`.`	Repository root.

Each line is <file>:<start_line>-<end_line> (score <score>).

rce-code search "authentication middleware" -k 5

search-semantic

Embedding cosine-KNN (vector) search. Returns nothing until chunks are embedded — run rce-code embed first. See Semantic Search.

Argument / Option	Default	Description
`QUERY` (positional)	—	The search query.
`-k`, `--top-k`	`10`	Maximum number of results.
`--repo`	`.`	Repository root.

search-semantic

rce-code embed
rce-code search-semantic "where do we validate the JWT" -k 5

search-hybrid

Reciprocal-Rank-Fusion of lexical + semantic + symbol search. Run embed first to include semantic results. See Hybrid Search.

Argument / Option	Default	Description
`QUERY` (positional)	—	The search query.
`-k`, `--top-k`	`10`	Maximum number of results.
`--repo`	`.`	Repository root.

search-hybrid

rce-code index
rce-code embed
rce-code search-hybrid "rate limit the login endpoint" -k 10

grep

Grep the working tree via ripgrep. Fixed-string by default; pass --regex to treat the pattern as a regular expression. See Grep.

Argument / Option	Default	Description
`PATTERN` (positional)	—	The pattern to search for.
`--regex` / `--literal`	`--literal`	Treat `PATTERN` as a regex (otherwise a fixed string).
`--repo`	`.`	Repository root.

Each line is <file>:<line>:<column> <line_text>.

grep

# Fixed-string (default)
rce-code grep "TODO"

# Regular expression
rce-code grep --regex "def\s+test_\w+"

grep flag is a toggle pair

--regex/--literal is a single boolean flag pair defaulting to --literal. The richer grep options exposed on the Python API (glob, case_sensitive, max_count, raw) are not surfaced as CLI flags — reach for the Python API when you need them.

embed

Embed chunks that lack a current embedding. Prints embedded N chunk(s). Run this after index and before the semantic / hybrid searches. See Embedders.

Argument / Option	Default	Description
`--repo`	`.`	Repository root.

embed

rce-code embed

symbols

List the symbol definitions in a single file, in source order.

Argument / Option	Default	Description
`FILE` (positional)	—	Repo-relative file path.
`--repo`	`.`	Repository root.

Each line is tab-separated: <start_line>\t<kind>\t<qualified_name>.

symbols

rce-code symbols src/auth.py

find

Find symbol definitions named NAME anywhere in the repo.

Argument / Option	Default	Description
`NAME` (positional)	—	Exact symbol name to find.
`--repo`	`.`	Repository root.

Each line is <file>:<start_line>\t<kind>\t<qualified_name>.

find

rce-code find login

refs

Show references to NAME — both calls and imports, including unresolved ones. By default shows all references; --imports narrows to import references only.

Argument / Option	Default	Description
`NAME` (positional)	—	Target name to look up.
`--imports` / `--all`	`--all`	Only import references (otherwise calls + imports).
`--repo`	`.`	Repository root.

Each line is <from_file>:<line>:<col>\t<import|call>\t<to_name>.

refs

# All references to "login"
rce-code refs login

# Only the import references
rce-code refs login --imports

callers

Show the resolved callers of the symbol(s) named NAME. Resolves the name to symbol(s), then lists every symbol that calls them via the resolved call graph.

Argument / Option	Default	Description
`NAME` (positional)	—	Symbol name whose callers to show.
`--repo`	`.`	Repository root.

Each line is <file>:<start_line>\t<qualified_name> (one per caller).

callers

rce-code callers authenticate

callees

Show the resolved callees of the symbol(s) named NAME — the symbols those definitions call.

Argument / Option	Default	Description
`NAME` (positional)	—	Symbol name whose callees to show.
`--repo`	`.`	Repository root.

Each line is <file>:<start_line>\t<qualified_name> (one per callee).

callees

rce-code callees authenticate

repomap

Print a relevance-ranked repository map fit to a token budget, biased toward the files and identifiers you name. See Repo Map.

Argument / Option	Default	Description
`--focus`	— (repeatable)	File(s) to bias the map toward. Pass multiple times for multiple files.
`--ident`	— (repeatable)	Identifier(s) mentioned in context. Pass multiple times for multiple idents.
`--budget`	`1024`	Token budget for the generated map.
`--repo`	`.`	Repository root.

repomap

rce-code repomap \
  --focus src/auth.py \
  --focus src/session.py \
  --ident login \
  --budget 2048

--focus and --ident are repeatable

Both --focus and --ident are multiple-value options — repeat the flag once per value rather than passing a comma-separated list.

A typical session

session.sh

# 1. Build the index for the current directory
rce-code index

# 2. Embed so semantic and hybrid search work
rce-code embed

# 3. Check index health
rce-code stats

# 4. Query
rce-code search "session store"
rce-code search-hybrid "where do we refresh tokens" -k 5
rce-code find refresh_token
rce-code callers refresh_token
rce-code repomap --focus src/session.py --budget 1024