CLI reference

Every command takes an optional [path] argument (defaults to .). Most accept additional flags listed below.

commands

init · sync · analyze · ingest · enrich · status
link · skills · profile · learn · dashboard
serve · canvas · verify · clean
triage audit · agents (list / eval / run)

init

codegps init [path]

Creates <path>/.codegps/ with empty code.db, knowledge.db, and a stub config.json. Registers the project in ~/.codegps/global.db.

sync

codegps sync [path] [--full]

Re-indexes the L0 code graph.

Flag	Effect
`--full`	Ignore content hashes and re-parse every file.

Output:

L0 sync complete: 142 files, 2041 nodes, 3177 edges

analyze

codegps analyze [path] [--full]

Code-grounded analysis (the tree-sitter + LLM hybrid). For each indexed file it builds a deterministic payload from code.db — definitions, resolved imports, call-sites — plus a bounded source slice, and runs the FileAnalyzer agent to produce a plain-English summary, an architectural layer (api · service · data · ui · utility · other), tags, and language concepts. A directory-level ArchitectureAnalyzer pass then reconciles layers. Results land in code.db.file_analysis.

Flag	Effect
`--full`	Re-analyze every file, ignoring content hashes.

Incremental: a file whose content_hash is unchanged since its last analysis is skipped. Also runs inside ingest (disable with --no-analyze).

ingest

codegps ingest [path] [--agent <id>] [--no-triage] [--no-extract] [--no-analyze] [--no-enrich] [--reprocess]

Pulls new conversation data, runs the agent pipeline (L1.5→L3), the code-grounded analysis (L0.5), then the enrichment pass (L2.5).

Flag	Effect
`--agent cursor\|claude-code\|codex\|copilot`	Limit to one adapter.
`--no-triage`	Skip the Triage Agent — useful when the LLM is offline.
`--no-extract`	Skip extractor agents — populate L1/L1.5 only.
`--no-enrich`	Skip the L2.5 enrichment pass.
`--reprocess`	Re-run triage / extract / cluster over all existing windows, not just newly ingested ones. Use after a model swap or an interrupted run.

ingest is incremental — it only processes windows created this run. If a previous run finished cleanly, a re-run reports zeros because there is nothing new. --reprocess forces a full re-pass.

Output:

Ingest complete:
  Sessions seen:    24 (new: 3)
  Turns ingested:   58
  Windows created:  19
  Triaged:          19 (kept 14, dropped 5)
  Facts produced:   31
  Concepts:         6 created, 14 attached
  Domain entities:  8
  Relationships:    11
  Knowledge gaps:   2

enrich

codegps enrich [path] [--no-agent]

Runs the L2.5 enrichment pass on its own: manifest + SQL structural extraction, entity reconciliation, technical-skill synthesis, domain modeling, industry classification, industry enrichment, and gap detection. Works for any project type — frontend, library, or schema-heavy backend — using whatever signal exists (code, manifests, conversations).

Flag	Effect
`--no-agent`	Structural + deterministic gaps only (no LLM): manifests, SQL entities, reconciliation, detected gaps.

Counts in the report are rows added this run, not totals. A re-run over already-enriched data shows zeros; use codegps status for true totals.

status

codegps status [path]

Counts per layer, broken down by scope and grounding. Cheap, read-only.

serve

codegps serve [path] --mcp

Runs the MCP server over stdio. See MCP integration for client wiring and the tool catalogue.

canvas

codegps canvas <kind> [path]

Generates a self-contained .canvas.tsx under .codegps/canvas/.

Kind	Purpose
`triage-audit`	Every triaged window with labels and rationale; filter by kept/dropped/domain.
`project-map`	L3 concepts grouped with member facts and L0 code links.
`decision-timeline`	Chronological view of decisions, business rules, problems / solutions.
`business-logic`	Domain rules and entities, grouped by concept.
`cross-project-bridge`	Shared concepts across two or more registered projects.

link

codegps link [path] [--rebuild]

Rebuilds the L4 cross-project graph and the L5 skill graph: exports this project's concepts and enrichment evidence to ~/.codegps/global.db, runs mechanical matching, the Linker Agent, then synthesizes skills across all registered projects.

Flag	Effect
`--rebuild`	Wipe `concept_links` first; re-compute from scratch.

skills

codegps skills [--scope technical|industry] [--cross] [--limit <n>]

The global skill graph (L5): what you know, weighted by evidence across projects. Each row shows evidence weight, grounding, and project count.

Flag	Effect
`--scope`	Filter to `technical` or `industry` skills.
`--cross`	Only skills present in more than one project.

profile

codegps profile [--prose] [--out <path>]

The big-picture second-brain summary across all projects: classified industries, top technical skills by evidence weight, and the grounding mix. Read-only over global.db.

Flag	Effect
`--prose`	Generate portfolio/background markdown via the ProfileWriter agent (consumes domain highlights + skills + industries).
`--out <path>`	Where to write the prose (default `~/.codegps/profile.md`).

ProfileWriter respects grounding: structural/corroborated skills are stated as demonstrated; stated ones are hedged; nothing is invented.

learn

codegps learn [path] [--limit <n>]

Learning targets: industry-standard knowledge (grounding model / external) the IndustryEnricher surfaced that is not yet grounded in your own work. These are general domain knowledge, explicitly distinct from facts about your project.

verify

codegps verify [path] [--prune-below <n>] [--max-pairs <n>] [--invalidate-triage-days <n>]

Runs the Verifier sweep:

Prune orphan facts whose confidence falls below the threshold (default 0.25).
For each cluster with multiple same-kind facts, pairwise verify (cap per cluster).
Optionally invalidate triage cache entries older than N days so the next ingest re-triages them.

dashboard

codegps dashboard [path] [--open]

Builds a self-contained interactive graph dashboard from the project's SQLite databases: a file-level dependency graph (nodes colored by architectural layer), domain highlights/entities, L3 concepts, and a fuzzy search index. Emits a single offline-openable index.html (graph inlined) plus a shareable graph.json to <project>/.codegps/dashboard/.

Flag	Effect
`--open`	Open the generated dashboard in your browser.

Build the viewer bundle once with npm run build:dashboard (or npm run build:all). See the dashboard guide.

clean

codegps clean [path] [--local-only] [--global-only] [--all] [--yes]

Removes a project's knowledge: its local .codegps/ and/or its rows in the global brain. The skill graph is re-aggregated after global rows are removed. Runs as a dry run by default — it prints the plan and only deletes with --yes.

Flag	Effect
`--local-only`	Only delete the local `.codegps/` directory.
`--global-only`	Only delete this project's rows in `~/.codegps/global.db`.
`--all`	Full reset: every registered project's local data + the global brain (keeps `config.json`).
`-y, --yes`	Skip the dry run and actually delete.

triage audit

codegps triage audit [path] [--dropped] [--limit <n>]

Lists triaged windows with their labels and rationale. Use --dropped to inspect what triage filtered out and decide whether to tune.

agents

codegps agents list
codegps agents eval [path] [--agent <name>]
codegps agents run <name> [path]

list shows registered agents and their prompt versions. eval runs every golden fixture under __tests__/agents/<name>/ against the configured backend and prints PASS / FAIL. run executes a single agent over its pending input — handy for debugging prompt or schema changes.