CLI for Agents & CI/CD Pipelines — Optimal Docs

Using Optibot CLI with CI/CD Pipelines

The Optibot CLI was created for both use in typical development environments for engineers and for use within CI/CD pipelines and fully autonomous agent environments like Claude Code, Codex, and others.

Install

npm install -g @optimalai/optibot

Getting API Keys (For Agents & CI/CD)

API keys (optk_*) are long-lived credentials for non-interactive environments such as agentic coders and CI/CD pipelines. Generate them on a dev machine, then store the key in your CI provider’s secrets.

optibot login opens a browser and will refuse to run inside a CI environment (it detects CI, GITHUB_ACTIONS, GITLAB_CI, and similar). Do the steps below on your local machine, not in the pipeline.

Recommended: guided setup

optibot setup ci

optibot setup ci walks the whole flow: it logs you in if needed, confirms the active organization (re-scoping your token if you pick a different one), 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 name prompt, and --non-interactive to error on any missing input instead of prompting (useful in scripts).

Because API keys are bound to the organization active at creation, run optibot org switch first if you need the key to act as a specific organization.

Manual alternative

If you prefer to do it by hand:

  1. Authenticate via the CLI on your dev machine:
optibot login
  1. 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.

  1. Set the key as an environment variable:
export OPTIBOT_API_KEY=optk_your_key_here

You can also list and delete your keys directly from the CLI:

# List all API keys
optibot apikey list

# Delete a key by ID
optibot apikey delete KEY_ID

Environment Variables

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

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

CI/CD Integration

Setup

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

Advisory vs blocking reviews

By default optibot review exits 0 and posts feedback without failing the job — the review is advisory. To make a failing review block the build (and therefore the merge), add --fail-on-issues: the command exits non-zero when the review does not pass. The recipes below are advisory; add the flag to gate.

optibot review --branch origin/main --fail-on-issues

Running Reviews in CI

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

Security Scans in CI

The same OPTIBOT_API_KEY also authorizes optibot scan. Run scans non-interactively with --json for machine-readable output, and branch on the stable exit codes (0 success, 2 auth, 3 insufficient credits, 4 a scan is already running, 5 not found, 6 invalid request). See Security Scans for the full command group and billing model.

optibot scan run my-repo --json

Review Output

After each review, the CLI displays: