CLI Reference¶
The Topos CLI is for manual inspections and terminal workflows when
you want structural quality verdicts without an editor integration. Most
agent workflows use the MCP server instead — it currently
covers more ground than the CLI (preference-ranked relaxation walks and
structured agent guidance). The CLI is a fresh,
from-scratch Rust implementation built directly on topos-engine, not a
line-for-line port of the pre-v0.4.0 Python CLI — some Python-CLI features
haven’t been ported yet; each command below says explicitly what’s missing.
Hint
evaluate automatically resolves GitNexus for COMPOSABLE scoring and
supports JSON, priority, and preference inputs. MCP remains the richer
agent surface: it returns the full preference walk, refactor targets,
findings, and structured contracts.
Quick reference¶
topos install
topos status
topos evaluate . -r
topos config
topos inspect module.py
topos compare before.py after.py
topos coverage src/logic.py --tests tests/test_logic.py
topos depgraph generate
topos mcp
Run topos mcp as a smoke check, then stop it with Ctrl-C.
Classify files, drill into metrics, measure AST drift, and score structural test overlap.
evaluate · inspect · compare · coverage
Agent registration, project settings, and the MCP server.
install · status · uninstall · config · depgraph · mcp
Quality commands¶
evaluate¶
Evaluate code quality for one or more files or directories. This is the primary command for Code Quality Medals across the four pillars (see Measures).
topos evaluate [PATHS]... [OPTIONS]
Option |
Description |
|---|---|
|
Recursively evaluate directories. |
|
Optional discovery filter. Omit it and every supported language is discovered, each file parsed with its inferred language — the same multi-language default as MCP project evaluate. A named path that misses the filter, or does not exist, errors with the real cause. |
|
Print every file’s full classification and raw metrics. |
|
Emit a machine-readable document without terminal progress. Each result
carries its own |
|
Select one of the five weakest files in a TTY and show its top three
line-level refactor targets. When piped, inspect the weakest file
without prompting. Combine with |
|
List every file whose policy gates fail the selected pillar, ordered by
that pillar’s diagnostic score. Cannot be combined with |
|
Either a single pillar ( |
|
Skip GitNexus and score SIMPLE/SECURE only. |
|
Use a non-default |
Example
topos evaluate . -r # every supported language
topos evaluate . -r --failures simple
topos evaluate . -r --info
topos evaluate . -r --failures simple --info
topos evaluate . -r --language rust # narrow to one language
For a directory, terminal output is a cumulative pillar table with status,
average and minimum diagnostic scores, failure counts, quality rails, and the
directory lattice floor. When a pillar fails, a short hint points to
--failures PILLAR for the exact files; --info adds a bounded
Weak spots list ranked by each file’s average diagnostic score.
Opening a row reveals the
weakest pillar, ranked metrics, exact source spans, and recommended operations.
Combining --failures PILLAR --info applies the same browser to the five
lowest-scoring files that actually fail that pillar. A low score alone does
not put a file in the list: failure status always comes from policy gates.
Progress is drawn on stderr only while work is active.
Press Enter to open a file, Escape to return to the selector, and
Escape again (or q) to close it.
Single-file runs use the same compact summary without redundant aggregate
columns and point to topos inspect for the full file-level analysis.
Use --verbose only when a script or debugging session needs the legacy
inline raw-metric stream.
Representative directory output. The second line names the language when every
discovered file agrees and N languages when they do not:
◇ Evaluated 20 files
│ 3 languages · priority simple · COMPOSABLE enabled
│
│ PILLAR STATUS AVG MIN FAILURES SCORE
│ SIMPLE X FAIL 51% 0% 3 / 20 ━━━━━━━◆───────
│ COMPOSABLE X FAIL 60% 0% 8 / 20 ━━━━━━━━◆──────
│ SECURE ✓ PASS 100% 100% 0 / 20 ━━━━━━━━━━━━━━◆
│
│ Status reflects policy gates; scores are diagnostic — use them to guide refactoring.
└ ✓ 🥈 SILVER · SIMPLE_SECURE · 70% average.
Tip: add --failures simple to list its 3 failing files; --info shows overall weak spots.
When COMPOSABLE cannot be scored, the reason appears on the finished card rather than as mid-run noise, and recoverable cases point at the fix:
◇ Evaluated 20 files
│ 3 languages · priority simple · COMPOSABLE not measured
│ ↻ GitNexus generation failed (Not inside a git repository.) — COMPOSABLE not scored
Note
Pillar status comes from the raw policy gates. Normalized quality scores
are diagnostic and therefore can be below the visual midpoint even when a
pillar passes. --failures filters on those gates rather than scores.
--info exposes the same ranked refactor-target evidence used by MCP
without expanding every project row or rerunning the project.
inspect¶
Inspect one file without losing the project context. Human output starts with
the same pillar summary as evaluate, then shows ranked recommendations,
function complexity with line spans, and every raw metric. Policy metrics keep
their interpretations; supporting diagnostics remain available in a quieter
section.
topos inspect PATH [OPTIONS]
Option |
Description |
|---|---|
|
Output the inspection as a single JSON object (a subset of the
pre-v0.4.0 Python CLI’s |
|
Skip GitNexus and inspect SIMPLE/SECURE only. |
|
Use a non-default |
Example
topos inspect src/main.py
topos inspect src/main.py --json
The nearest .topos.toml supplies the inspection priority and preferences,
so file-level guidance stays aligned with the project. JSON field names and
values are unchanged by the human-output redesign.
compare¶
Compare structural (AST) distance between two programs — topological drift via UAST edit distance, not line-level diff.
topos compare SOURCE TARGET [OPTIONS]
Option |
Description |
|---|---|
|
Show insertions, deletions, and substitutions. |
Example
topos compare old_version.py new_version.py -v
coverage¶
Measure how much of the program-under-test (PUT) structure is represented in test code.
Declaration-level bipartite matching and k-gram path recall. No test execution required. See Measures for the underlying algorithm.
topos coverage SOURCE_PATHS... --tests TEST_PATH [OPTIONS]
Option |
Description |
|---|---|
|
Test file or directory; repeat for multiple test paths. |
|
Recursively discover files when source or test paths are directories. |
|
Language for parsing. Inferred when all discovered files use one language; required for mixed-language inputs. |
|
DFS kind n-gram length for path recall (default: |
|
Minimum best-match recall to count a PUT declaration as covered (default: |
|
Include |
Example
topos coverage src/logic.py --tests tests/test_logic.py --k 3
Directories use the same ignored-path discovery rules as evaluate:
topos coverage src/ --tests tests/ -r --language python
The headline reports mean declaration coverage. The following line reports the percentage of individual source declarations meeting the configured threshold. Topos rejects inputs with no measurable source or test declarations instead of treating an empty corpus as covered.
Note
--json is not yet ported to this CLI — plain-text output only. The
same computation is exposed with structured JSON via the
topos_calculate_coverage MCP tool.
Other commands¶
install / uninstall / status¶
Register the Topos MCP server in your agent harnesses, and take it back out.
One entry per harness, with an absolute command path; no skill files, no
instruction blocks. See For Agents for the harness table and state model.
topos install [HARNESSES]... [OPTIONS]
topos uninstall [HARNESSES]... [OPTIONS]
topos status [--json]
Harness ids: claude, claude-desktop, codex, gemini,
copilot, cursor, vscode, antigravity.
Flag |
Behavior |
|---|---|
|
Target every supported harness. Required in a non-interactive shell
when no ids are given ( |
|
Print the plan and write nothing. |
|
|
|
|
|
|
With no ids in a terminal, both commands open a multi-select checklist.
topos uninstall always previews what it will remove and asks first;
topos install status is an alias for topos status.
Example
topos install --all --dry-run # see what would change
topos install claude codex # just those two
topos status --json # for scripts and agents
config¶
View or update project evaluation settings in the nearest .topos.toml.
Running bare topos config opens a small priority selector on a TTY and
falls back to show when input is non-interactive.
topos config
topos config show
topos config set --priority secure
topos config set --priority composable,secure,simple
--priority accepts either form: a single pillar sets the emphasis and
reorders the existing ranking around it; a full comma-separated ranking
replaces it outright. Explicit evaluate flags override project settings.
A full ranking is the stronger statement of intent, so its first pillar
becomes the effective priority.
On disk, [evaluation].priority is a single key: a pillar string
(priority = "secure") or a full ranking array
(priority = ["composable", "secure", "simple"]). config set always
writes the array form. A legacy preferences array is still read when
present, then dropped on the next write.
depgraph¶
Build or refresh the GitNexus store used by COMPOSABLE scoring. Generation
no-ops when the existing graph is current unless --force is supplied.
topos depgraph generate [PATH] [OPTIONS]
Option |
Description |
|---|---|
|
Project directory to analyze (default: current directory). |
|
Regenerate even when the graph is current. |
|
Output the generation result as a single JSON object. |
Requires GitNexus on PATH. evaluate and inspect normally manage
the same store automatically; this command is useful for explicit refreshes
after dependency changes. If a graph reported as current appears stale, rerun
with --force. When evaluate cannot measure COMPOSABLE, its terminal
summary points back to this command.
mcp¶
Start the Topos Model Context Protocol server on stdio. AI coding agents connect to this instead of shelling out to evaluate.
topos mcp
Tip
Verify the binary before wiring it into an editor (see For Agents):
topos mcp
The command waits on standard input. Press Ctrl-C to exit.
Next steps¶
Installation — install the binary or build from source
For Agents — wire Topos into Claude Code, Cursor, Gemini CLI, and other MCP clients
Measures — what each pillar measures and how thresholds map to medals
Concepts — lattice and characteristic-morphism background