Review your local diff before it becomes a merge request.

What you need

• PHP 8.2 or newer.
• Composer.
• A git repository with local changes.
• A CodeGuards API key from Integrations.
• Your organization slug and repository connection id from CodeGuards.

1. Install the CLI

Install once on your machine so the codeguards command is available in every repository. The installer checks PHP/Composer, installs the package, updates your shell PATH, and verifies the command.

curl -fsSL https://codeguards.io/dist/codeguards-install.sh | sh

Expected result: the CLI prints the command list and ends with CodeGuards CLI is ready. Open a new terminal tab after installation so your shell reloads the updated profile.

Prefer manual install? Run the Composer commands and add its global bin directory to PATH:

composer global config repositories.codeguards composer https://codeguards.io/dist/composer
composer global require codeguards/ci-runner
CG_BIN="$(composer global config bin-dir --absolute | awk 'END{print}')"
export PATH="$CG_BIN:$PATH"
grep -qxF "export PATH=\"$CG_BIN:\$PATH\"" ~/.zshrc || echo "export PATH=\"$CG_BIN:\$PATH\"" >> ~/.zshrc
codeguards

2. Connect your repository

Open the repository you want to review and initialize CodeGuards.

cd /path/to/your/repository
codeguards init

The CLI asks for three values:

• CodeGuards API key — generated in the workspace integrations page.
• Organization slug — copied from your CodeGuards workspace.
• Repository connection id — copied from the repository row in CodeGuards.

The normal flow does not ask for an API URL. Production is the default: https://codeguards.io/ci/reviews.

3. Verify setup

codeguards doctor

Expected result:

[ok] config loaded
[ok] credentials loaded
[ok] git repository detected

4. Review local changes

Review staged, unstaged, and untracked files:

codeguards review --mode=all

Generate and open an HTML report with changed files, snippets, findings, and recommendations:

codeguards review --mode=all --products=review,security --report-html --open

If your plan does not include security, CodeGuards will only return the products available to your workspace.

5. Work with findings

codeguards show --finding=1
codeguards open --finding=1
codeguards chat --finding=1 --message="why does this matter?"
codeguards fix --finding=1 --dry-run
codeguards suppress --finding=1 --reason="accepted risk for this test"
codeguards hallucination --finding=1 --reason="not true in this code path"

Where files are stored

.codeguards/config.json                  repository settings
~/.config/codeguards/credentials.json    API key, chmod 0600
.codeguards/session.json                 last review session
.codeguards/report.html                  latest HTML report

Generated session and report files are ignored by the CLI's local .codeguards/.gitignore. Do not commit credentials.

Troubleshooting

• command not found — add Composer's global bin directory to PATH, or install inside the repository and use ./vendor/bin/codeguards.
• Missing API key — run codeguards init or set CODEGUARDS_API_KEY.
• No local changes found — check git status --short, then run codeguards review --mode=all.
• Repository connection id must be numeric — copy the numeric id from the repository row in CodeGuards.