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:

1. preparing projects;
2. checking system state;
3. running reviews and reports;
4. 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¶

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

If Something Breaks¶

First check:

1. Is the project imported?
2. Is the API running?
3. Is OpenViking healthy?
4. Is PostgreSQL reachable?
5. Is GoCPG healthy?

Then read: Troubleshooting

Related Guides¶

• Quick Reference
• OpenCode Quick Start
• Project Import