Docs · Quickstart

Quickstart

Install the CLI, run a scan, understand the exit codes, and wire AIOptimize into CI. Everything here runs locally — no account, no telemetry.

Install

We recommend pipx, which keeps the CLI isolated from your project virtualenv.

bash

# pipx keeps the CLI on PATH without polluting your project
$ pipx install aioptimize

# Or install into your existing environment
$ pip install aioptimize

# Confirm install
$ aioptimize --version
aioptimize 0.1.0

First scan

From the root of any repo that calls the Anthropic or OpenAI SDKs:

~/app — aioptimize scan .

$ aioptimize scan .

Scanning 142 files (Python: 96, TS/JS: 46)
KB version 2026.04.15 · 37 detectors · verified 3 days ago

warn   D001  Anthropic system prompt without cache_control
       src/agents/router.py:42  client.messages.create(...)
       Suggested: add cache_control={"type":"ephemeral"} to the system block

warn   D002  Deprecated model version
       src/workers/summarize.ts:18  model: "claude-2.1"
       Suggested: migrate to claude-sonnet-4-5

info   D003  messages.create without max_tokens
       src/chat/stream.py:87

Done. 2 warn, 1 info · 0 error

Want machine-readable output? Use --format json or --format markdown.

Exit codes

By default AIOptimize always exits 0 so it never surprises your CI. Opt into failure with --fail-on-severity.

Code	Meaning
0	Scan completed, no findings above the configured threshold.
1	Scan completed with findings at or above `--fail-on-severity`.
2	Invalid CLI usage (bad flag, missing path).
3	Internal error while scanning — please file an issue.

CI integration

Drop-in GitHub Actions workflow. Runs on every pull request and posts a Markdown report as a sticky comment.

.github/workflows/aioptimize.yml

name: aioptimize
on:
  pull_request:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install AIOptimize
        run: pipx install aioptimize
      - name: Scan
        run: aioptimize scan . --format markdown > report.md --fail-on-severity warn
      - name: Comment on PR
        if: always()
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          path: report.md

Prefer inline PR annotations, Slack notifications, and trend charts? Those ship with the Team plan.

Next: detector reference

Every detector has a rationale, an example diff, and a link to the upstream provider guidance. The full catalog is coming soon — for now, see the v0.1 summary in the docs overview.