CLI guide

The codebeaver CLI reviews local Git diffs, calls Worker endpoints for GitHub-aware tasks, and prints either terminal text or machine-readable JSON. It can also run a smaller single-pass review against an OpenRouter-compatible provider without a hosted session.

Install

Requirements:

• Node.js 20 or newer;
• Git for local diff commands;
• GitHub CLI for fix --pr-url;
• access to the private @codebeaver GitHub Packages scope.

GitHub Packages requires a classic personal access token with read:packages, and the GitHub account behind that token must be allowed to read the package. Keep the token out of the repository. One per-user setup is:

npm login --scope=@codebeaver --auth-type=legacy --registry=https://npm.pkg.github.com

Enter your GitHub username and use the token as the password. See GitHub's npm registry authentication guide if your organization supplies credentials another way.

npm install -g @codebeaver/cli --registry=https://npm.pkg.github.com
codebeaver --version

The package contains its own SKILL.md. codebeaver skills install copies that file into supported project-level agent directories.

Authenticate

codebeaver auth login --client-id YOUR_GITHUB_OAUTH_CLIENT_ID

The service operator supplies the OAuth client ID. Pass it once with --client-id or set CODEBEAVER_CLIENT_ID; a successful login saves it in config.json for refreshes.

The CLI opens GitHub OAuth in a browser, listens on a temporary loopback callback, exchanges the code with the Worker, and writes the session token with mode 0600.

Files live under ~/.config/cli/:

File	Contents
token	Worker session JWT
config.json	Worker URL, OAuth client ID, username, and refresh data
last-review.json	Most recent review response plus repository and SHA metadata

Useful commands:

codebeaver auth status
codebeaver auth refresh
codebeaver auth logout
codebeaver doctor

CODEBEAVER_TOKEN takes precedence over the token file. If it is set, auth logout clears the file but cannot unset the process environment.

The service URL resolves in this order:

1. CODEBEAVER_URL;
2. workerUrl in config.json;
3. https://codebeaver.workers.dev.

You can also pass the global --url option. Non-local URLs must use HTTPS.

Select a diff

Review-like commands accept one or more of these options:

Option	Git operation
--diff <text>	Use the supplied text without running Git
--staged or -t staged	git diff --cached --no-ext-diff
-t uncommitted	git diff --no-ext-diff
-t committed	git diff --no-ext-diff origin/main...HEAD
-t all	git diff --no-ext-diff HEAD
--base <ref>	Compare <ref>...HEAD where the command accepts a base

-t is the short form of --type. With no selector, review-like commands use --type all.

If Git returns no usable diff, the CLI reads standard input when it is piped. Refs beginning with - are rejected.

Examples:

codebeaver review --type uncommitted
codebeaver review --staged
codebeaver review --type committed --base origin/develop
git show --format= | codebeaver review --agent

Command reference

Review and change analysis

Command	Network behavior	Main options
review	/api/cli/review, except --local	--type, --base, --staged, --diff, --title, --description, --agent, --json, --local, --skip-validation, --profile, --fail-on
fix	/api/cli/review	--pr-url, --diff, --type, --base, --staged, --agent, --json
simplify	/api/cli/improve in simplify mode	--base, --staged, --diff, --title, --agent, --json
improve	/api/cli/improve	--base, --staged, --diff, --title, --json
describe	/api/cli/describe	--base, --staged, --diff, --title, --json
walkthrough	/api/cli/describe	--base, --staged, --diff, --title, --json
test	/api/cli/test	--base, --staged, --diff, --title, --agent, --json
changelog	/api/cli/changelog	--since, --commits, --json

review --profile accepts security, performance, types, scope, mentor, or a repository profile. --focus is a compatibility alias. review --skip-validation explicitly skips the hosted second pass. Otherwise, findings must pass validation even after a slow primary response; a validator outage returns an error. Local mode ignores --skip-validation because it has no validator, and accepts built-in profiles only; repository profiles need a hosted review so the Worker can load the repository policy.

fix does not edit files. It prints recommendations from the review findings without another model pass. Scanner findings without a recommendation retain their issue text. Check these proposals against the source before applying them. It defaults to unstaged changes, or committed changes when --base is supplied; an explicit --type selects that scope. For --pr-url, it uses the requested repository and PR head SHA for context and cache metadata.

GitHub pull-request commands

Command	What it does
autofix --pr-url <url>	Asks the Worker to prepare a verified autofix branch for an internal PR
ask --pr-url <url> --question <text>	Posts an answer based on the PR diff
coverage --pr-url <url>	Posts changed-source and matching-test analysis

autofix needs the GitHub App installation for the target repository. The caller repository also needs the reusable auto-fix.yml workflow described in the GitHub App guide.

SARIF

codebeaver sarif \
  --file reports/current.sarif \
  --baseline reports/main.sarif \
  --fail-on warning

The command accepts SARIF files up to 1 MB, normalizes findings through /api/cli/sarif, and removes baseline matches. --fail-on accepts none, error, warning, or any.

Export the stored, validated findings for a reviewed PR as SARIF 2.1.0:

codebeaver sarif \
  --pr-url https://github.com/codebeaver/codebeaver/pull/123 \
  --output codebeaver-123.sarif

The export contains only findings that passed model validation or came from deterministic scanners. It includes finding origin, validation state, intent status, and metadata-only evidence references. The command needs CLI authentication and writes SARIF to stdout when --output is omitted.

Scanner output is not merged into stored AI review findings. GitHub code-scanning upload remains a separate step. See scanner workflows.

Codebase index and search

codebeaver index --repo codebeaver/codebeaver --branch main
codebeaver search \
  --repo codebeaver/codebeaver \
  --query "installation token lookup" \
  --top-k 10 \
  --agent

index accepts --files, --diff, or the tracked files in a matching local checkout. One request indexes at most 200 files. Source is split into bounded chunks, embedded with Workers AI, and stored under a hashed repository namespace.

Search returns paths and line ranges, not a promise that every result is relevant. Review context uses exact graph and GitHub code-search candidates before Vectorize paths.

Cached findings and agent handoff

Every successful hosted or local review, plus each successful fix, writes the local last-review.json. Replay it without another model call:

codebeaver findings
codebeaver findings --bundle --output .codebeaver-findings.json
codebeaver handoff --target codex --bundle .codebeaver-findings.json

The stable bundle uses schema_version: "v1" and combines AI and SAST findings under source-prefixed IDs. Handoff targets are codex, claude-code, and cursor. Without --bundle, handoff prints the cached findings as fix instructions. With --bundle <path>, it also writes a mode-0600 bundle at that path. --json returns the bundle and instructions as one object.

The CLI warns when the cache belongs to another repository or commit. It does not block replay.

Learning rules

codebeaver learning --repo codebeaver/web-admin
codebeaver learning approve \
  --repo codebeaver/web-admin \
  --kind fp \
  --pattern "example pattern"
codebeaver learning reject \
  --repo codebeaver/web-admin \
  --kind bp \
  --pattern "example rule"
codebeaver learning delete --repo codebeaver/web-admin --kind fp --rule-index 2

--kind fp addresses false-positive rules. --kind bp addresses learned practice rules. Omitting --rule-index from learning delete clears that rule list for the repository.

Repository config helpers

codebeaver config inspect
codebeaver config generate > .codebeaver.yaml

inspect reports the detected package manager, TypeScript config, and common test config. generate prints a starter file. Neither command reads the effective org or repository config from GitHub; use @codebeaver config on a PR for that.

Skill installation

codebeaver skills install
codebeaver skills install --agent codex
codebeaver skills install --global
codebeaver skills list

Project-level installation supports Claude Code, Cursor, Codex, Hermes, GitHub Copilot, CodeBuddy, Windsurf, OpenCode, Gemini CLI, Cline, Junie, Goose, Amp, Qwen, and Trae.

Machine-readable output

--json prints the endpoint response. --agent prints a command-specific v1 object intended for coding loops. Errors use this shape in agent mode:

{
  "schema_version": "v1",
  "ok": false,
  "error": {
    "code": "NO_DIFF",
    "message": "No diff found."
  }
}

Review agent output contains verdict, findings, sast_findings, fix_context, and stats. Fix output contains fixes plus the original findings. Test output contains proposed test files and source. Search output contains repository paths, scores, and chunk line ranges.

Do not parse terminal text. Use --json, --agent, or a finding bundle.

Exit status

review --fail-on controls finding-related status:

Value	Exit 1 when...
never	Never because of the verdict or findings
verdict	Verdict is request_changes or error
any	Any AI or SAST finding exists
warning	A warning or critical finding exists
critical	A critical finding exists

Invalid review --fail-on values are rejected before a provider call. Command errors use a nonzero status and one JSON error object when --agent or --json is selected. Empty command results remain valid JSON with --json. sarif --fail-on independently sets status 1 when new external SARIF findings meet its selected threshold.

Local provider mode

export CODEBEAVER_LOCAL_BASE_URL=http://127.0.0.1:11434/v1
export CODEBEAVER_LOCAL_MODEL=qwen2.5-coder:14b
codebeaver review --local --focus security

Variables and fallbacks:

Variable	Use	Default
CODEBEAVER_API_KEY	Preferred provider bearer token	OPENROUTER_API_KEY
OPENROUTER_API_KEY	Fallback provider bearer token	none
CODEBEAVER_LOCAL_BASE_URL	Preferred OpenAI-compatible API root	CODEBEAVER_API_BASE_URL, then OpenRouter
CODEBEAVER_API_BASE_URL	Fallback OpenAI-compatible API root	OpenRouter
CODEBEAVER_LOCAL_MODEL	Model name	openai/gpt-4o-mini
CODEBEAVER_REFERER	HTTP referer sent to provider	project GitHub URL

Remote providers need HTTPS and an API token. Loopback HTTP providers may omit the token. The request timeout is 120 seconds.

Local mode sends the raw diff directly to the configured provider. It does not redact secrets on the client, so inspect the diff before sending sensitive code. It omits the hosted SAST pass, validator, GitHub installation context, repository config, feedback rules, usage record, and Worker-side analysis cache. The CLI still writes last-review.json after a successful local run. Malformed review objects return an error instead of an empty approval. Valid warning or critical findings produce request_changes; suggestions produce comment. Use local mode for fast feedback, not as a substitute for the GitHub check when those controls matter.

Suggested agent loop

edit
  -> codebeaver review --agent --type uncommitted
  -> apply supported findings
  -> run repository checks
  -> codebeaver review --agent --type uncommitted
  -> commit

Retain the original base and diff selector when re-reviewing. Commit fixes before re-reviewing committed changes, and regenerate explicit or piped diffs. -t all checks tracked working-tree changes; it does not include committed changes.

Keep the repository's own tests as the source of truth. Generated tests and fix blocks are proposals until they compile and pass.

Review before you push

A hosted review records the exact commit and ignore-filtered diff it covered (reviewed-sha:v1:{repo}:{sha}, 30-day retention) when the signed-in user has push access and validation completed. Commit the changes and run codebeaver review --agent --type committed --base origin/main before git push, replacing origin/main with the PR target branch; when the PR review later sees the same commit and diff, the Worker already knows about it. Repos with auto_review.previously_reviewed: skip finalize their AI Code Review check from the recorded local verdict (verdict pass-through: approve becomes a green check, request_changes a red one) and post a short notice; the default recheck mode reruns the remote review but still benefits from the content caches. /review forces a fresh run either way.