2.1 ● DOCS / CLIreference

CLI

Review a local git diff from your terminal. Same engine as the GitHub App — run it before you push.

Install

The CLI is published to npm. Requires Node.js 20 or newer.

npm install -g @codecommentsai/cli

This drops a codecomments launcher into npm's global bin directory. If that directory isn't on your PATH, npm prints a warning — add the shown directory to your shell rc and reopen the terminal.

Pin a specific version with npm install -g @codecommentsai/cli@1.2.3. Prefer yarn or pnpm? Their global add commands work the same way.

Authenticate

Interactive (recommended for laptops):

codecomments login

A browser opens for sign-in and device approval. The CLI writes the token to ~/.config/codecomments/config.json with 0600 permissions. You never see or copy it.

Headless (CI, containers, SSH): generate a token at dashboard → settings → CLI tokens. Copy it when shown — you won't see it again. Then:

# as a positional argument (convenient locally)
codecomments auth ccmt_xxxxxxxxxxxxxxxxxxxxxxxx

# or piped on stdin (safer — never appears in process listings)
printf '%s' "$CODECOMMENTS_TOKEN" | codecomments auth

XDG_CONFIG_HOME overrides the config location. Pass --api-url <url> to login or auth to target a self-hosted backend — later review runs reuse the saved URL.

Review

By default, the CLI diffs the current branch against origin/main.

codecomments review

Against a different base ref:

codecomments review --base origin/develop

From a patch file or stdin:

codecomments review --diff my.patch
git diff main...feature | codecomments review --stdin

Machine-readable JSON output for scripts:

codecomments review --json

Exit codes

0 — review completed, no P1 findings.

1 — either the review completed with at least one P1 finding, or the CLI failed to run (auth, network, unreadable diff, rate limit). The error message on stderr distinguishes the two.

Use a non-zero exit in pre-push hooks and CI to block on blocking bugs.

CI example

A GitHub Actions job that blocks merges on P1 findings:

- name: Install CodeComments CLI
  run: npm install -g @codecommentsai/cli

- name: Authenticate
  # Pipe the token on stdin so it stays out of ps and /proc/<pid>/cmdline.
  run: printf '%s' "$CODECOMMENTS_TOKEN" | codecomments auth
  env:
    CODECOMMENTS_TOKEN: ${{ secrets.CODECOMMENTS_TOKEN }}

- name: Review
  run: codecomments review --base origin/${{ github.base_ref }}

The job exits 1 on any P1 finding and passes otherwise. P2–P4 findings print but don't block. Piping the token on stdin keeps it out of process listings and audit logs.

Rate limits

20 reviews per hour per user. A 429 response tells you when the window resets.

Very large diffs may be truncated. The CLI flags this in the output so you know the review wasn't exhaustive.

Commands

codecomments login

Browser-based auth. Accepts --api-url and --timeout <minutes>.

codecomments auth [<token>]

Save a token locally. Omit the argument to read from stdin. Accepts --api-url <url>.

codecomments review [flags]

Review a diff.

codecomments whoami

Print the saved token's fingerprint and the configured API URL.

codecomments --help

Full usage.