CodeGraph command-line guide

The root CodeGraph CLI is a source-checkout interface. From the repository root, use:

python -m src.cli --help

Do not assume that installing the Python wheel creates a codegraph executable. The current pyproject.toml publishes only codegraph-acp and codegraph-lsp console scripts. A deployment may provide its own operator wrapper; verify that wrapper with its own --help before use.

Command shape

The canonical source form is:

python -m src.cli <command> [subcommand] [options]

Start with help at the exact level you need:

python -m src.cli import --help
python -m src.cli projects --help
python -m src.cli audit --help
python -m src.cli review --help
python -m src.cli doctor --help

Help output from the installed release is authoritative for flags and value choices. Examples in documentation never authorize retired aliases or parameters absent from that output.

Safe first commands

Run diagnostics before mutation:

python -m src.cli doctor --json
python -m src.cli projects list
python -m src.cli languages

For a project-specific action, pass or resolve an explicit project scope. Do not rely on an unexplained active-project fallback, and do not pass raw storage paths through agent-facing interfaces.

Common workflows

Use Project import for the full import lifecycle and Troubleshooting for recovery.

Source target search and diff preview

The current edit surface supports find and preview only:

python -m src.cli edit find <pattern> --file PATH
python -m src.cli edit preview file.py::name --new-code-file PATH

find searches supported source files. preview reads the target and proposed replacement and prints a diff; it does not write the source file. The registered apply, undo, and history subcommands are not yet implemented and return exit code 1. There is no public REST or MCP editing route. Apply an accepted change through the governed implementation workflow with tests, review, and rollback rather than treating a preview as mutation evidence.

Service-account lifecycle

Administrators can inspect the supported machine-identity lifecycle from the current parser:

python -m src.cli auth service-account --help
python -m src.cli auth service-account create --help
python -m src.cli auth service-account list --help
python -m src.cli auth service-account inspect --help
python -m src.cli auth service-account rotate --help
python -m src.cli auth service-account revoke --help
python -m src.cli auth service-account deactivate --help

Treat credentials returned by create or rotate as one-time sensitive output. Bind the account to the minimum required actions and project scope, preserve credential identity rather than the secret in evidence, and verify revoke or deactivate before closing an access-removal request. See RBAC for authorization and mTLS boundaries.

Traceability snapshots

The dashboard CLI exposes the current snapshot lifecycle:

python -m src.cli dashboard snapshot --help
python -m src.cli dashboard snapshot show --help
python -m src.cli dashboard snapshot policy --help

Use show for immutable metadata and policy for the installed governance rules. Listing, comparison and export are also discoverable under the same help surface. There is no delete operation; release and portfolio evidence must preserve snapshot identity. See Traceability snapshots.

Automation

• Pin the CodeGraph release and repository revision.
• Call --help during compatibility checks instead of copying a frozen command inventory.
• Use explicit output paths for durable artifacts.
• Treat nonzero exit status as a failed operational postcondition, not as product acceptance evidence.
• Keep tokens and passwords in the approved secret mechanism, never command arguments or logs.

Contract sources

• src/cli/__main__.py — current root parser and command registration;
• src/cli/core_commands/ — import and project command parsers;
• src/cli/core_commands/auth_commands.py — service-account lifecycle commands;
• src/cli/dashboard_suite/dashboard_command_registration.py — snapshot commands;
• src/cli/governance_suite/doctor_commands.py — diagnostic command surface;
• src/cli/docs_suite/edit_commands.py — supported target search/diff preview and explicit stateful stubs;
• pyproject.toml — installed codegraph-acp and codegraph-lsp entry points.

See also: Quick reference · OpenCode quick start