Command doctor

Command: doctor

Diagnose the environment and project health.

Synopsis

columbus doctor [flags]

Description

Checks everything Columbus needs and reports a status line per item: the binary, git, ripgrep, ast-grep, the embedded grammars, the vec0 vector extension, the onnxruntime runtime (a dry run of the embedding model, with its dimension), and — inside a project — the config, data dir, database schema, index counts, and the embedding model the index was built with. A missing runtime is a warning (search degrades to keyword), not a failure. Use it first when something isn't working.

Flags

Global flags only (--json, --llm, --no-color).

Example

$ columbus doctor
[ok]   columbus     version 0.1.0
[ok]   git          /usr/bin/git
[ok]   ripgrep      /usr/bin/rg
[ok]   ast-grep     /usr/local/bin/ast-grep
[ok]   grammars     6 languages loaded
[ok]   config       project proj_2fd171eebe922fad
[ok]   data_dir     /your/data/dir
[ok]   database     schema v4
[ok]   vec0         sqlite-vec v0.1.6
[ok]   index        4 files, 7 symbols
[ok]   embedding    bge-small-en-v1.5 (384-d)
[ok]   runtime      bge-small-en-v1.5 (384-d)

healthy

When the embedding runtime is absent, runtime and embedding warn instead of fail:

[warn] runtime      onnxruntime not loadable (keyword fallback)
    hint: install onnxruntime or set COLUMBUS_ORT_LIB to its path, then run 'columbus doctor'

--json emits the same checks as a machine-readable report for agents/CI.

Exit codes

0 healthy (or usable with warnings) · 1 a hard check failed. See Exit Codes and Troubleshooting.

See also

Installation · Troubleshooting