CodeGraph CLI Guide

This guide explains the command line in plain language.

Use CLI when you want:

imports and refresh jobs;
scripts and automation;
checks in CI;
direct access without the OpenCode plugin.

What the CLI Is For¶

The CLI is not the main daily interface for most people anymore. That role belongs to OpenCode.

The CLI is now best for:

preparing projects;
checking system state;
running reviews and reports;
automating repeatable work.

The Three Things You Usually Need¶

1. Import a project¶

codegraph import --path /path/to/repo

Use this when you first bring a repository into CodeGraph.

What happens:

the code graph is built with GoCPG;
project context is prepared for OpenViking;
the project becomes available to the API and plugin flows.

2. List projects¶

codegraph projects list

Use this when you want to confirm that the project exists and is ready.

3. Start the API¶

python -m src.api.cli run

Use this when OpenCode, MCP, or another tool needs the backend.

Common Everyday CLI Jobs¶

Review changes from CLI¶

python -m src.cli review --base-ref HEAD~3

Use this when you want review findings without opening the plugin.

Run project-level checks¶

python -m src.cli audit --db data/projects/codegraph.duckdb --language en --format json

Use this when you want a broad quality or risk pass.

Refresh project state¶

codegraph import --path /path/to/repo

Use the same import path again when the repository changed enough that you want a clean refresh.

Manage service accounts¶

python -m src.cli auth service-account create --name ci-bot
python -m src.cli auth service-account list
python -m src.cli auth service-account inspect --service-account-id sa_123
python -m src.cli auth service-account rotate --service-account-id sa_123
python -m src.cli auth service-account revoke --service-account-id sa_123 --credential-id cred_456
python -m src.cli auth service-account deactivate --service-account-id sa_123

Use these commands when automation needs an explicit machine identity and you want to control its full lifecycle from the CLI.

Inspect snapshots and governance policy¶

python -m src.cli dashboard snapshot show --snapshot-id snap_123
python -m src.cli dashboard snapshot policy

Use dashboard snapshot show when you need to inspect one stored baseline, and dashboard snapshot policy when you need to confirm the current governance rules before compare or export.

How CLI Fits the New Architecture¶

Even when you use CLI, the same system model still applies:

GoCPG gives the live graph;
OpenViking gives reusable project memory;
PostgreSQL keeps governance and ownership rules.

So CLI work still affects the same sessions, memory, and project state that OpenCode uses later.

When to Use CLI Instead of OpenCode¶

Use CLI when…	Use OpenCode when…
You need repeatable scripts	You are doing interactive daily work
You are preparing or refreshing a repo	You are exploring or reviewing code live
You want a backend check in `CI`	You want guided commands like `/onboard` or `/review`
You want raw operational control	You want the shortest path to an answer

Fast Command List¶

# Import a repository
codegraph import --path /path/to/repo

# Show projects
codegraph projects list

# Start API
python -m src.api.cli run

# Review changes
python -m src.cli review --base-ref HEAD~3

# Run an audit
python -m src.cli audit --db data/projects/codegraph.duckdb --language en --format json

# Service-account lifecycle
python -m src.cli auth service-account create --name ci-bot
python -m src.cli auth service-account list
python -m src.cli auth service-account inspect --service-account-id sa_123
python -m src.cli auth service-account rotate --service-account-id sa_123
python -m src.cli auth service-account revoke --service-account-id sa_123 --credential-id cred_456
python -m src.cli auth service-account deactivate --service-account-id sa_123

# Snapshot inspection and policy
python -m src.cli dashboard snapshot show --snapshot-id snap_123
python -m src.cli dashboard snapshot policy

Command Surface Index¶

Use this section as a compact inventory of the currently supported CLI entry points. It is intentionally command-first so docs-sync can verify the public surface without repeating every tutorial in full prose.

Root `codegraph` command groups¶

codegraph audit progress --help
codegraph audit markup-status --help
codegraph audit-diff --help
codegraph audit-log --help
codegraph audit-log export --help
codegraph audit-log stats --help
codegraph auth ldap-status --help
codegraph auth oauth-status --help
codegraph auth permissions --help
codegraph auth roles --help
codegraph auth service-account --help
codegraph changelog --help
codegraph compliance report-57580 --help
codegraph compliance report-57580-delta --help
codegraph compliance report-57580-history --help
codegraph coverage --help
codegraph coverage show --help
codegraph dashboard compare --help
codegraph dashboard compare-periods --help
codegraph dashboard dora-aggregates --help
codegraph dashboard dora-snapshot --help
codegraph dashboard gocpg-log --help
codegraph dashboard integration-profile --help
codegraph dashboard integration-profile show --help
codegraph dashboard notifications --help
codegraph dashboard red-zone --help
codegraph dashboard release-compare --help
codegraph dashboard saved-views --help
codegraph dashboard saved-views delete --help
codegraph dashboard saved-views get --help
codegraph dashboard saved-views list --help
codegraph dashboard saved-views save --help
codegraph dashboard snapshot --help
codegraph dashboard stability --help
codegraph dashboard trends --help
codegraph deps --help
codegraph dynamic --help
codegraph dynamic correlate --help
codegraph dynamic findings --help
codegraph dynamic fuzz-targets --help
codegraph dynamic report --help
codegraph dynamic runs --help
codegraph edit --help
codegraph gitverse bindings --help
codegraph gitverse review-dry-run --help
codegraph gitverse template --help
codegraph hypothesis --help
codegraph hypothesis export --help
codegraph hypothesis list-cwes --help
codegraph hypothesis providers --help
codegraph issues --help
codegraph issues bulk-create --help
codegraph issues create --help
codegraph issues sync --help
codegraph issues update --help
codegraph llm --help
codegraph llm providers --help
codegraph llm test --help
codegraph optimize --help
codegraph optimize analyze --help
codegraph optimize apply --help
codegraph optimize approve --help
codegraph optimize list-suggestions --help
codegraph optimize reject --help
codegraph optimize undo --help
codegraph projects --help
codegraph qualification --help
codegraph qualification coverage --help
codegraph qualification error-catalog --help
codegraph qualification metrics --help
codegraph qualification report --help
codegraph reindex --help
codegraph release --help
codegraph release suppressions --help
codegraph repos --help
codegraph repos connect-provider --help
codegraph repos slices --help
codegraph risk --help
codegraph risk anomalies --help
codegraph risk assess --help
codegraph risk checklist --help
codegraph risk checklist export --help
codegraph risk detail --help
codegraph risk events --help
codegraph risk events classify --help
codegraph risk matrix --help
codegraph risk org-docs --help
codegraph risk org-docs generate --help
codegraph risk org-docs status --help
codegraph risk report-fincert --help
codegraph risk threat-model-57580 --help
codegraph risk threat-model-57580 diff --help
codegraph risk threat-model-57580 review-status --help
codegraph sbom --help
codegraph sbom generate --help
codegraph sbom gost-report --help
codegraph sbom sync --help
codegraph security --help
codegraph security incident --help
codegraph siem --help
codegraph siem status --help
codegraph siem test --help
codegraph standards --help
codegraph supply-chain --help
codegraph vault --help
codegraph vault rotate --help
codegraph vault status --help

Standalone Python CLIs¶

python -m src.api.cli init-db
python -m src.api.cli migrate --revision head
python -m src.api.cli create-admin --username admin --password change-me
python -m src.cli.security_audit quick --path ./repo
python -m src.cli.security_audit settings --path ./settings.py
python -m src.cli.security_audit secrets --path ./repo
python -m src.cli.generate_docs section mvd_doc --language en
python -m src.cli.generate_docs index --path ./docs/generated

GoCPG Binary Commands¶

The standalone GoCPG entrypoint is gocpg.

gocpg branches --help
gocpg branches list --help
gocpg branches prune --help
gocpg branches switch --help
gocpg callees --help
gocpg callers --help
gocpg ci-update --help
gocpg deps --help
gocpg frontends --help
gocpg frontends list --help
gocpg hierarchy --help
gocpg hooks --help
gocpg hooks install --help
gocpg hooks status --help
gocpg hooks uninstall --help
gocpg index --help
gocpg metrics --help
gocpg outline --help
gocpg quality-stats --help
gocpg resolve --help
gocpg scan --help
gocpg scope --help
gocpg search --help
gocpg serve --help
gocpg submodules --help
gocpg submodules list --help
gocpg submodules prune --help
gocpg symbols --help
gocpg type-stats --help
gocpg usages --help

If Something Breaks¶

First check:

Is the project imported?
Is the API running?
Is OpenViking healthy?
Is PostgreSQL reachable?
Is GoCPG healthy?

Then read: Troubleshooting

Supplemental Command Coverage¶

These commands are part of the current public CLI surface and are listed explicitly because they are easy to miss in scenario-oriented guides:

projects current returns the effective active project after workspace, user-preference, and access resolution.
projects resolve explains which project would be selected for the current workspace and why.
projects switch persists a project preference explicitly when an operator wants to override auto-resolution.
repos provider-health checks health, credentials, and connectivity for a configured repository provider connection.
repos rotate-provider-token rotates provider credentials without recreating the repository binding.
repos repair-openviking repairs OpenViking-backed repository/project memory state for a bound repository.
repos repair-context-sessions repairs context-session lifecycle records for a project.
repos bootstrap-memory bootstraps project memory for a repository binding without re-importing the repository.