Skip to main content
Start any investigation with: 
kodus status
kodus auth status
kodus review --verbose    # or any command with --verbose
kodus status shows the consolidated state (auth mode, org, repo, hook, version). --verbose prints the resolved API URL and per-request details.

​
Common Errors

The CLI isn’t on your PATH. Reinstall with your package manager’s global flag, or use npx @kodus/cli <command> for one-off runs.
  • npm install -g @kodus/cli
  • yarn global add @kodus/cli
  • pnpm add -g @kodus/cli
  • bun add -g @kodus/cli
If you installed via the skill installer, re-run curl -fsSL https://review-skill.com/install | bash to fix PATH entries.
  • Run kodus auth status to see the current mode.
  • If using a team key, verify it’s still active at app.kodus.io/organization/cli-keys.
  • If using personal login, try kodus auth login again — the refresh token may have expired.
  • For CI, confirm KODUS_TOKEN (or KODUS_TEAM_KEY) is set in the environment the pipeline runs in.
  • If self-hosted, confirm KODUS_API_URL points to the correct instance.
kodus review requires a git working directory. cd into a repo or initialize one with git init. For kodus config repo commands, you can pass owner/repo explicitly instead of ..
Large branches (hundreds of files, thousands of lines) can take several minutes. The default request timeout is 60 minutes — you should see progress in verbose mode.
  • Use --verbose to confirm the request is in flight.
  • For very large diffs, prefer --branch <base> or --commit <sha> over working-tree mode: these let the backend clone the same commit instead of receiving inlined file contents.
  • Override the timeout with KODUS_REQUEST_TIMEOUT_MIN=90 kodus review if needed.
  • Split work across smaller branches when practical.
Review honors the ignore-files patterns configured in kodus config repo. List current settings with:
kodus config repo show
You can add or remove patterns:
kodus config repo add-ignore-file . "**/*.generated.ts"
kodus config repo remove-ignore-file . "**/*.generated.ts"
Binary files, images, and lockfiles are skipped by default.
Trial mode allows 5 reviews per day. Sign in with kodus auth login or configure a team key via kodus auth team-key --key kodus_xxxxx to raise limits. kodus auth status prints your current usage.
Your KODUS_API_URL is hitting a reverse proxy or Cloudflare Access page instead of the API. Check:
  • The URL path (no stray /api, /v1, etc.).
  • Cloudflare Access credentials (CF_ACCESS_CLIENT_ID, CF_ACCESS_CLIENT_SECRET) if applicable.
  • That the proxy forwards Authorization and CF-Access-* headers intact.
The CLI rejects non-HTTPS API URLs for everything except localhost and 127.0.0.1. Provision a valid TLS certificate for your self-hosted instance, or use http://localhost:<port> for local development.
  • Confirm installation: kodus hook status.
  • Make sure .git/hooks/pre-push is executable.
  • Other hook managers (Husky, Lefthook, pre-commit) may overwrite .git/hooks/pre-push. Either chain them or reinstall with kodus hook install --force.
  • Skip the hook for a single push: KODUS_SKIP_HOOK=1 git push.
  • Run kodus decisions status to see which agents are wired up.
  • Re-run kodus decisions enable --force to reinstall integration files.
  • For Codex, ensure ~/.codex/config.toml contains the notify = ["kodus", "decisions", "capture", ...] line, or pass --codex-config <path>.
  • Check the agent actually emits turn-complete events (some older Claude Code configurations don’t).
Self-hosted instances can enforce device limits per organization. Ask your admin to increase the limit or remove unused devices from the dashboard.

​
Exit Codes

Use these in scripts and CI pipelines.
CodeMeaning
0Success. No issues found, or issues were found but below --fail-on.
1Issues found at or above the --fail-on severity.
2CLI usage error (invalid flag, missing argument).
3Authentication or authorization failure.
4Network or API error (timeout, 5xx, invalid response).
5Not in a git repository, or no changes to review.
For CI, pair --fail-on error with --format json and --output review.json to surface structured results as pipeline artifacts without affecting the exit code logic.

​
Debugging Tips

  • --verbose on any command prints the resolved API URL, request IDs, and timings.
  • kodus schema outputs the machine-readable command schema — useful when your agent reports a missing flag.
  • --agent enforces deterministic, machine-readable output; combine with --format json when scripting.
  • KODUS_VERBOSE=true persists verbose mode across multiple commands in a session.

​
Getting Help

  • Report bugs: github.com/kodustech/cli/issues
  • Feature requests, configuration questions: your Kodus account manager, or support@kodus.io.
  • For self-hosted deployments, include kodus status --verbose output when filing an issue.