Optibot CLI — Getting Started and Installation

The Optibot CLI expands Optibot’s capabilities by letting Optibot be used by both humans and agents through a terminal or virtual environment of choice.

The CLI is available directly through npm as a published package and is regularly updated and maintained by the Optimal AI Engineering Team.

Requirements for Installation

• Node 20.0.0 or above
• Git
• Windows / Mac / Linux
• A paid or trial subscription to Optibot. Login here or sign up here.

Install

npm install -g @optimalai/optibot

Upgrading from the optibot package

The CLI is now published as @optimalai/optibot. If you installed the older optibot package, replace it:

npm uninstall -g optibot
npm install -g @optimalai/optibot

Updating

npm install -g @optimalai/optibot@latest

Check what you are running, and what is published:

optibot --version
npm view @optimalai/optibot version

The CLI and the Claude Code skill are separate packages with separate version numbers, and updating one leaves the other where it was. The skill runs the CLI, so update both in the same pass.

New skill behaviour lands behind a CLI minimum. Agent review mode needs CLI 0.8.0 or later; an older CLI answers --agent with unknown option.

Authentication

1. Browser-Based OAuth (Recommended for Interactive Use)

Best for local development and interactive CLI usage:

optibot login

This will:

• Open your browser for login
• Automatically save your credentials
• Token expires after 90 days

Use this when:

• Setting up CLI on your local machine
• You have browser access
• Interactive development workflow

2. API Key (For Agents & CI/CD)

See the CLI for CI/CD Pipelines guide for headless authentication.

How to Use the CLI

# Review local uncommitted changes
optibot review

# Review against the auto-detected base branch (origin/main, origin/master, or origin/develop)
optibot review -b

# Review changes against a specific branch
optibot review --branch origin/main

# Review an arbitrary diff file
optibot review --diff changes.patch

# Exit non-zero when the review does not pass (for git hooks / CI)
optibot review --fail-on-issues

# Use the previous synchronous review behavior
# (only needed against older self-hosted backends)
optibot review --sync

By default optibot review is advisory: it always exits 0 and simply prints feedback. Add --fail-on-issues to make it exit non-zero when the review does not pass, so it can gate a git pre-push hook or a CI step. See CLI for Agents & CI/CD Pipelines for using it in a pipeline.

Large reviews

Reviews of large diffs complete reliably from CLI 0.7.3 onward. In earlier versions, very large reviews could fail with a timeout error (HTTP 524) before finishing. Reviews of any size now run to completion, with live progress in your terminal as before, and nothing needs to be configured. Run optibot --version to see which version you are on.

Upgrading is a drop-in change. Your existing optibot review commands, scripts, and CI configuration keep working with no edits, and there is nothing new to turn on. Older CLI versions still work as well, so you can upgrade on your own schedule; only v0.7.3 and later include the large-diff fix, so upgrade to resolve the timeout.

The --sync flag

optibot review --sync runs a review the previous way, in a single request. It exists only for running the CLI against an older self-hosted backend that predates this change. It also brings back the previous timeout on large diffs, so do not use it to work around a timeout: for that, upgrade instead. On the hosted service you never need --sync.

Branch Review

When using -b / --branch, the CLI will:

1. Auto-detect the base branch if no branch name is provided. It checks for origin/main, origin/master, and origin/develop in that order.
2. Check for merge conflicts before submitting the review. If conflicts are detected with the target branch, a warning is displayed.
3. Generate a diff and collect file contents for the review.

Review Output

After each review, the CLI displays:

• Review Summary — general comments about the changes
• File Comments — per-file feedback with line numbers
• Rate limit info (only when a daily cap is in force) — reviews used, remaining quota, and time until reset

The rate limit line appears only when a daily cap is in force. An account with no cap has no quota to report, so the CLI omits that line.

When it does appear, it is color-coded:

• Dim when usage is normal
• Yellow when 10% or less of the daily allowance remains
• Red when the quota is exhausted

Organizations & Status

If you belong to more than one organization, the CLI acts as one active organization at a time. Use optibot status to see how you are authenticated and which organization is active, and optibot org switch to change it. See Organizations & Account Status for the full picture, including how API keys are bound to an organization.

# Show auth status, active organization, and review quota
optibot status

# List your organizations / switch the active one
optibot org list
optibot org switch

Security Scans

Beyond code review, the CLI can run AI-powered security scans against your repositories with optibot scan. See Security Scans for the full command group, model tiers, budgets, scheduled scans, and token billing.

# Trigger a security scan on a repository (by id or name)
optibot scan run my-repo

Commands Reference