CodeGraph command-line guide

This guide covers CLI use in a prepared local CodeGraph source checkout. You need Python 3.11 or later, the project dependencies, and Git for file comparison. Server installation is covered in the installation guide.

In the examples, python means the interpreter of the environment containing CodeGraph dependencies. If that environment is in .venv, use .\.venv\Scripts\python.exe or activate the environment before running commands. CLI execution requires security.local_cli_enabled: true in the local config.yaml. Change only that setting and preserve the rest of the configuration. Enable it only for local development. The message CodeGraph CLI is disabled. means that execution was rejected; the command returns exit code 2. After a successful invocation, check the output data.

From the repository root, run:

python -m src.cli --help

The Python package publishes codegraph-acp and codegraph-lsp console scripts. Run the main source-checkout CLI through python -m src.cli. 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 from the installed release lists the supported flags and value choices. Use it when composing a command for that release.

Safe first commands

Start by checking configuration from the repository root:

python -m src.cli doctor config --json

The JSON report has scope=config. Inspect config.config_yaml and config.projects_yaml to see whether the configuration and project-registry files are valid. For overall_status=pass, the command returns exit code 0; warnings produce 1 and failures produce 2.

Then collect the full diagnostics and project and language information:

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. Agent-facing interfaces use the project identifier; the server resolves its storage binding from context.

Common workflows

Use Project import for the full import lifecycle, Run a CPG-backed project audit for audit modes and evidence, and Troubleshooting for recovery.

Find a function and compare files

The edit find command searches source code elements. To try it with a small example, save this complete file as example.py:

def greeting(name):
    return "Hello, " + name

From the CodeGraph checkout root, run this command in PowerShell. If the file is elsewhere, replace example.py with its quoted path:

python -m src.cli edit find greeting --file example.py --exact

The output should identify the greeting function in example.py. If no name matches, the command prints No targets found matching and returns exit code 0. Check the returned elements as well as the exit code. The source file is unchanged.

The current implementation registers edit preview, but a call with a valid target fails with AttributeError: 'DiffGenerator' object has no attribute 'generate_diff'. Do not rely on this command for a working preview.

To compare two files, save the proposed version as replacement.py:

def greeting(name):
    return f"Hello, {name}!"

With Git installed, run:

git diff --no-index -- example.py replacement.py

The output should remove return "Hello, " + name and add return f"Hello, {name}!". Git returns exit code 1 when the files differ and 0 when they match. This compares whole files and leaves both unchanged. The proposed greeting ends with an exclamation mark.

The apply, undo, and history commands are not implemented and return exit code 1 with a not yet implemented message. Apply an approved change in your editor, then run the project’s tests and review its diff.

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.
• Check what the exit code means for each command. For example, git diff returns 1 when files differ. An exit code alone does not establish product acceptance.
• Keep tokens and passwords in the approved secret mechanism, never command arguments or logs.

Reference material

If a command fails, use the troubleshooting guide.

See also: Quick reference · OpenCode quick start