@optimalai/optibot

CLI tool for running AI code reviews and security scans powered by Optibot.

Install

npm install -g @optimalai/optibot

After installing, verify:

optibot --version
optibot --help

Authentication

Optibot CLI supports two authentication methods:

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
• If you belong to more than one organization, an arrow-key picker appears so you can choose which one this session should use (see Organizations)

Use this when:

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

2. API Keys (For Automation & CI/CD)

Best for non-interactive environments:

1. First, authenticate via the CLI:

   optibot login

2. Create an API key:

   optibot apikey create ci-github-actions

   The output includes the key (starts with optk_). Copy it immediately — it is only shown once.

3. Set the key as an environment variable:

   export OPTIBOT_API_KEY=optk_your_key_here

You can also list and delete your keys:

# List all API keys
optibot apikey list

# Delete a key by ID
optibot apikey delete KEY_ID

Use this when:

• Running in CI/CD pipelines (GitHub Actions, GitLab CI, etc.)
• Automated scripts or cron jobs
• Docker containers or headless environments

Environment Variables

• OPTIBOT_API_KEY — Your API token (for automation/CI/CD)
• OPTIBOT_API_URL — Backend URL (defaults to https://agents.getoptimal.ai)

Organizations

Your tokens (both browser-issued JWTs and optk_* API keys) are scoped to a single organization. Reviews, scans, usage, and other actions always run against that organization.

Picking an organization at login

If your account belongs to multiple organizations, optibot login shows an interactive arrow-key picker right after the browser flow. Pick one with the arrow keys and press Enter — the CLI rescopes the saved token to that organization.

If you only belong to one organization, no picker appears.

Switching organization later

You can change the active organization at any time without re-authenticating in the browser:

# Show all organizations you belong to (current is marked with *)
optibot org list

# Show only the currently active organization
optibot org current

# Interactive picker to switch the active organization
optibot org switch

optibot org switch issues a new token scoped to the chosen organization and replaces the one in ~/.optibot/config.json. All subsequent commands run against the new organization.

Notes for API keys

optk_* API keys created via optibot apikey create are permanently bound to whatever organization was active at creation time. To create a key for a different organization, run optibot org switch first, then optibot apikey create.

Usage

# 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

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. The review still proceeds, but results may not reflect the final merged state.
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 — reviews used, remaining quota, and time until reset. The display is color-coded:
  • Dim when usage is normal
  • Yellow when less than 10% of reviews remain
  • Red when the quota is exhausted

CI/CD Integration

Setup

1. Generate an API key (see API Keys above)
2. Add it as a repository secret (e.g., OPTIBOT_API_KEY in GitHub → Settings → Secrets)

GitHub Actions

name: Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install Optibot CLI
        run: npm install -g @optimalai/optibot
      - name: Run code review
        env:
          OPTIBOT_API_KEY: ${{ secrets.OPTIBOT_API_KEY }}
        run: optibot review --branch origin/${{ github.base_ref }}

GitLab CI

code-review:
  image: node:20
  script:
    - npm install -g @optimalai/optibot
    - optibot review --branch origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME
  variables:
    OPTIBOT_API_KEY: $OPTIBOT_API_KEY
  only:
    - merge_requests

Note: CI/CD requires API keys — OAuth login is not available in non-interactive environments.

Commands

| Command | Description | |---|---| | optibot login | Authenticate via browser (OAuth) | | optibot logout | Log out and remove saved credentials | | optibot review | Review local uncommitted changes | | optibot review -b | Review against auto-detected base branch | | optibot review -b <branch> | Review against a specific target branch | | optibot review -d <file> | Review a diff file | | optibot apikey create <name> | Create a new API key (scoped to the active organization) | | optibot apikey list | List all API keys | | optibot apikey delete <id> | Delete an API key | | optibot org list | List all organizations you belong to | | optibot org current | Show the currently active organization | | optibot org switch | Interactively switch the active organization | | optibot scan run <repo> | Trigger a security scan on a repository | | optibot scan list | List recent security scans | | optibot scan show <scan-id> | Show the full markdown report for a scan | | optibot scan usage | Show current-month token usage and cost | | optibot scan pricing | Show per-tier scan pricing | | optibot scan repos | List repositories available to scan | | optibot scan config | Show scheduled-scan configuration | | optibot scan config set | Update scheduled-scan configuration | | optibot status | Show auth method, profile, active organization, and review usage | | optibot --version | Print the installed CLI version | | optibot --help | Show top-level help; pass --help after any subcommand for subcommand-specific flags |

Security scans

Run AI-powered security scans against repositories in the active organization. Scans inspect your code, surface vulnerabilities (classified by severity), and optionally post the report as a GitHub/GitLab issue.

Billing model — read this first

Unlike optibot review (which has a daily review count quota), security scans are billed by token usage. Each scan deducts actual token cost × a markup multiplier from your organization's prepaid credit balance. The backend's response includes the actual cost and tokens consumed.

• Check your per-tier cost: optibot scan pricing
• Check what you've spent this month: optibot scan usage
• Cap what a single scan can spend with --budget <USD> (BE also enforces an organization-level default)
• If your balance can't cover the reserved budget, the CLI exits with code 3 and prints the top-up URL

Running a scan

# By repository id (find it with `optibot scan repos`)
optibot scan run 101

# By repository name (must be unambiguous in the active org)
optibot scan run my-app

# With a budget cap, a specific model tier, and post-as-issue on completion
optibot scan run my-app --budget 2.50 --model-tier medium --post-as-issue

The CLI subscribes to a live WebSocket progress channel for the scan — you'll see cloning_repository, scanning_code, tool calls, a rolling tokens: N · cost: $X.XX ticker, and finally Scan agent completed. When the scan finishes the CLI prints a summary with the actual cost, severity breakdown, and a pointer to optibot scan show <scan-id> for the full report.

Scans typically take 30 seconds to 5 minutes depending on model tier and codebase size. Poll timeout defaults to 10 minutes; override with --timeout <seconds>.

Viewing results

optibot scan list                      # latest scans (paginated)
optibot scan list --repo my-app        # filter to one repository
optibot scan show 42                   # rendered markdown report (TTY)
optibot scan show 42 --raw > report.md # raw markdown for piping/archiving

Scheduled scans

If you run scans regularly, configure a schedule so the backend triggers them automatically:

optibot scan config                                # show current config
optibot scan config set --enabled \
  --schedule weekly \
  --model-tier medium \
  --budget 10 \
  --repos 101,102,103 \
  --post-as-issue

Use --schedule custom --cron "0 0 * * 0" for a custom cadence.

JSON output (for Skills, MCPs, CI)

Every scan subcommand accepts --json and emits a single JSON object to stdout. No colors, no progress spinners, no interactive prompts. Example:

optibot scan run my-app --json | jq '{ id, issueCount, costUSD, severity }'
optibot scan usage --json | jq '.costUSD'

Exit codes

Stable for CI / scripting:

| Code | Meaning | |---:|---| | 0 | Success (scan completed) | | 1 | Generic failure (network, server 5xx, timeout, rate-limit) | | 2 | Auth failure (401 or 403) | | 3 | Insufficient credits (402) | | 4 | A scan is already running for this repository (409) | | 5 | Not found — repo, scan, etc. (404) | | 6 | Invalid request (400, including missing required flags) |

Use from CI

# GitHub Actions: fail the build if any critical vulnerabilities appear
- name: Optibot security scan
  env:
    OPTIBOT_API_KEY: ${{ secrets.OPTIBOT_API_KEY }}
  run: |
    set -e
    RESULT=$(optibot scan run my-app --json --budget 5 --timeout 900)
    CRITICAL=$(echo "$RESULT" | jq '.severity.critical // 0')
    if [ "$CRITICAL" -gt 0 ]; then
      echo "::error::Found $CRITICAL critical security issues"
      exit 1
    fi

optk_* API keys created via optibot apikey create are bound to the organization that was active at creation time, so a CI-scoped key always scans the right organization.

Requirements

• Node.js >= 20
• Git

Changelog

All notable changes are recorded here. The format follows Keep a Changelog and the project adheres to Semantic Versioning. Every released version has a matching git tag of the form vX.Y.Z.

0.4.0 — 2026-04-30

Added — Guided CI/CD onboarding

• New: optibot setup ci — guided CI/CD onboarding. Logs in if needed, confirms the active organization (rescoping the token if you pick a different org), mints a long-lived API key, and prints the export OPTIBOT_API_KEY=... line ready to paste into your CI provider's secret store. Use --key-name <name> to skip the key-name prompt, --non-interactive to error on any missing input.
• optibot status no longer fetches the user profile — the underlying /api/user/profile endpoint was never implemented on the backend. The Email: and Name: lines are removed; auth method, active organization, review quota, and the no-API-key nudge remain.
• Post-login prompt — after a successful optibot login, if the user has zero existing API keys, the CLI now offers to set up CI on the spot and walks through the same flow as setup ci.
• optibot apikey create <name> now prints the export OPTIBOT_API_KEY=... line and a hint to add it to your CI provider's secret store.
• optibot apikey list empty-state and optibot status (when no keys exist) now point users to optibot setup ci.
• optibot org switch reminds you that API keys are bound to the org active at creation, so you may need a fresh key for the new org.
• The "not authenticated" banner gains a third bullet for CI/CD setup.

Changed

• optibot login refuses to start a browser flow inside CI environments (CI=true, GITHUB_ACTIONS, GITLAB_CI, CIRCLECI, JENKINS_HOME, BUILDKITE, TRAVIS). Prints clear redirect instructions instead of hanging on the default 5-minute browser timeout.
• optibot setup ci performs the same CI-environment guard.

0.3.0 — 2026-04-21

Added

• Security scan command group (optibot scan ...):
  • scan run <repo> — trigger an AI-powered security scan with live WebSocket progress, --budget, --model-tier, --post-as-issue, --timeout, and --json flags
  • scan list — list recent scans with --repo, --page, --page-size, --json
  • scan show <scan-id> — render the full markdown report (--raw, --json)
  • scan usage — current-month token usage and cost
  • scan pricing — per-tier scan pricing
  • scan repos — repositories available to scan in the active organization
  • scan config / scan config set — view and update scheduled-scan configuration (weekly / monthly / quarterly / custom cron)
  • Stable exit codes for CI: 0 success, 1 generic failure, 2 auth, 3 insufficient credits, 4 conflicting scan, 5 not found, 6 invalid request
• Multi-organization support:
  • Arrow-key organization picker in optibot login when the user belongs to more than one organization
  • optibot org list — list all organizations (active marked with *)
  • optibot org current — show active organization
  • optibot org switch — interactive picker to rescope the stored token to another organization without a new browser login
• optibot --version now reports the actual package version (read from package.json at runtime) instead of a hard-coded placeholder.

Changed

• Auth flow migrated to the unified /client/* backend endpoints (/client/auth, /client/token, /client/token/verify, /client/token/rescope, /client/organizations). Legacy /vscode/* endpoints remain supported server-side for older clients.
• Organization identity is now read from the JWT claim organizationId rather than stored locally — switching org replaces the stored JWT.
• Zero-org users receive { status: 'onboarding_required', onboardingUrl } from /client/token; the CLI opens the URL and stores no token.
• apikey create keys are permanently bound to the organization active at creation — run org switch first to create a key for a different organization.
• Organization IDs are no longer shown in user-facing CLI output (names only).
• Package republished under the scoped name @optimalai/optibot. The unscoped optibot package is no longer maintained — install the scoped package only.

Fixed

• Suppress raw parser errors in login warnings and scan fallback output.
• Respect --no-post-as-issue in scan config set when disabling the flag.
• Shield printError against malformed JSON payloads that previously leaked stack traces to the terminal.
• Sanitize scan progress event fields before writing to the terminal (prevents terminal-escape injection via server-provided strings).
• Address three findings from the first internal security scan of the CLI.
• Handle Ctrl+C in the org switch picker as a clean exit rather than a thrown error.
• Validate branch existence before submitting a review to prevent confusing backend errors on invalid --branch targets.

Documentation

• README now documents security scans (billing model, usage, JSON output, exit codes, scheduled scans, CI recipe).
• README documents multi-organization support (login picker, org subcommands, API-key scoping).

0.2.0 — previously published (unscoped optibot package)

This version was published only to the legacy unscoped optibot name on npm. It is reproduced here for historical context; new installs should use @optimalai/optibot@^0.3.0.

Added

• optibot apikey create|list|delete — full CRUD for API keys.
• optibot status — show authentication method, profile, and review usage.
• Rate-limit information in review output (reviews used, remaining, reset time) with color-coded warnings.
• Auto-detect base branch in optibot review -b (checks origin/main, origin/master, origin/develop).
• Merge-conflict warning before submitting a branch review.

Security

• Fix shell injection via --branch argument (CRITICAL).
• Harden config-file permissions to owner-only (HIGH).
• Restrict --diff to files within the current directory (HIGH).
• Bind OAuth callback server to 127.0.0.1 only (MEDIUM).
• Sanitize server-returned text to prevent terminal-escape injection (MEDIUM).
• Warn when the API URL is overridden via environment variable (MEDIUM).

0.1.5 — previously published (scoped @optimalai/optibot)

Added

• Interactive browser-based OAuth authentication (optibot login, optibot logout).
• optibot review command — review local uncommitted changes, branch diffs, or arbitrary diff files.
• Vitest test suite with co-located tests and coverage configuration.
• Initial backlinks, license, and documentation.

Links

• Website
• Twitter / X
• LinkedIn
• YouTube
• Contact Us