Security Scans

The optibot scan command group runs AI-powered security scans against the repositories in your active organization. A scan analyzes a repository and produces a markdown report of findings. You can run a scan on demand, view past results, inspect token usage and pricing, and configure recurring scheduled scans.

Scans are billed by token usage against a prepaid AI-credit balance, separate from your code-review quota. See Billing below.

Running a Scan

# By repository name
optibot scan run my-repo

# By repository id
optibot scan run 42

The repository argument accepts either a repository id or its name (use the id if two repositories share a name). Run optibot scan repos to see what is available in the active organization.

While the scan runs, the CLI streams live progress over a WebSocket and then waits for the final report. When it finishes, the full result is printed to your terminal.

Options

If a scan does not finish before --timeout, the CLI stops waiting and exits non-zero. The scan keeps running on the server: check back later with optibot scan list, or re-run with a longer --timeout.

optibot scan run my-repo --budget 5 --model-tier high --post-as-issue

Listing Past Scans

optibot scan list

Lists recent scans for the active organization, most recent first.

Viewing a Scan Report

optibot scan show <scan-id>

Renders the full markdown report for a single scan. Pass the scan id from optibot scan list.

When output is not a terminal (for example, piped to a file), the report is emitted as raw markdown automatically.

Token Usage and Pricing

# Current-month token usage and cost for scans
optibot scan usage

# Per-tier scan pricing and markup multiplier
optibot scan pricing

Both commands accept --json. Use scan usage to track how much you have spent on scans this month, and scan pricing to see what each model tier costs before you run one.

Listing Scannable Repositories

optibot scan repos

Lists the repositories available to scan in the active organization, with their ids. Add --json for machine-readable output.

Scheduled Scans

Optibot can run scans on a recurring schedule without you triggering them. View the current configuration with:

optibot scan config

Update it with optibot scan config set:

# Enable a weekly scan on the high tier with a $5 budget for two repos
optibot scan config set --enabled --schedule weekly --model-tier high --budget 5 --repos 42,57

# Use a custom cron schedule
optibot scan config set --enabled --schedule custom --cron "0 3 * * 1"

# Turn scheduled scans off
optibot scan config set --disabled

Only the options you pass are changed; everything else keeps its current value.

Billing

Security scans are metered by token usage and billed against a prepaid AI-credit balance, which is separate from your monthly code-review quota.

• Set a ceiling per scan with --budget.
• Higher model tiers (--model-tier) produce deeper analysis but cost more per token.
• Check what you have spent this month with optibot scan usage, and per-tier rates with optibot scan pricing.

If your balance is too low to start a scan, the CLI exits with a clear message showing your current balance, the amount required, and a top-up link.

Exit Codes

The scan commands use stable exit codes so you can branch on them in CI scripts:

Combine these with --json to drive scans from automation. See CLI for Agents & CI/CD Pipelines for authentication in non-interactive environments.