Corgea CLI

Corgea CLI is a powerful developer tool that helps you find and fix security vulnerabilities in your code. Using our AI-powered scanner (blast) and our platform, Corgea identifies complex security issues like business logic flaws, authentication vulnerabilities, and other hard-to-find bugs. The CLI provides commands to scan your codebase, inspect findings, interact with fixes, and much more - all designed with a great developer experience in mind.

For full documentation, visit https://docs.corgea.app/cli

Installation

Using npm

npm install -g @corgea/cli

The npm package bundles native binaries for all supported platforms. The correct binary for your OS and architecture is selected automatically at runtime.

Using pip

pip install corgea-cli

Manual Installation

You can get the latest binaries for your OS from https://github.com/Corgea/cli/releases.

On Linux, both a -gnu and a -musl binary are published for x86_64 and aarch64. The -gnu builds run on glibc 2.17 and newer; the -musl builds are fully static and have no libc requirement at all, which makes them the safer pick for minimal containers and CI runners.

Setup

Once the binary is installed, login with your token from the Corgea app.

corgea login <token>

Scanning

corgea scan uploads your project and waits for results. corgea wait [scan_id] attaches to a running scan; corgea upload <report> --wait does the same for a third-party report.

All three exit 1 if the scan fails, printing the reason and the scanners that hit problems. A scan that completes with a scanner missing exits 0 with a warning. While waiting, the scan's status is read every 3 seconds. Waiting gives up after 10 hours; override with CORGEA_SCAN_TIMEOUT_SECONDS. --fail/--block-on then wait up to 15 minutes for blocking rules to be evaluated; override with CORGEA_BLOCKING_RULES_TIMEOUT_SECONDS.

--out-format/--out-file and --sbom are honored whether or not a gate trips: both are written before --fail/--block-on are evaluated, so a scan that exits 1 on a blocking rule still leaves its report behind to ingest.

Gateway errors are retried, not surfaced

Every Corgea API call the CLI makes — uploads included — replays itself when the platform's proxy answers 502 Bad Gateway, waiting 10s, then 30s, then 50s. A request that is still answered 502 after those three retries fails the command in the usual way, so a pipeline exits non-zero on a real outage and rides out the blips a busy platform produces under parallel scans. Each retry is logged, and the count belongs to a single request: any successful call starts the next one with the full three retries again.

The one place this stops early is corgea upload's per-file source upload: a 502 that outlives the retries there is taken as the platform being unavailable rather than one bad file, so the remaining paths are reported as unsent instead of each spending another 90 seconds.

Skipping a re-scan of the same commit

A pipeline that re-runs on an unchanged commit can reuse the scan it already has instead of paying for a duplicate:

corgea scan --skip-if-commit-scanned-recently --block-on criticals
corgea scan --skip-if-commit-scanned-recently --scanned-within 4h   # 90s, 30m, 4h, 7d

When the project already has a completed scan of the current commit inside the window (24h by default), that scan takes the new scan's place: the results table, the --block-on gate and its exit code, and any --out-file report all come from it, so the pipeline behaves the same whether or not a scan ran. The window exists because unchanged code is still exposed to advisories published since it was last scanned.

Two lines make the outcome scriptable — CORGEA_SCAN_SKIPPED=true plus CORGEA_SCAN_ID=<id> when a scan was reused, CORGEA_SCAN_SKIPPED=false when one ran — so a later step (an ingest, say) can branch on it.

Only a scan that answers the same question is reused, which is stricter than "same commit". A candidate has to be a completed BLAST scan of that commit, on a branch rather than a pull request, from an explicitly clean worktree, with no scanner problems reported — and this run has to be a default whole-commit scan itself. Anything else runs a real scan: nothing inside the window, only a failed or still-running scan, a worktree git status reports changes in, or a lookup the platform could not answer.

Two things are hard errors instead. An unresolvable commit (not a git repository, or no commits yet) exits 1 rather than silently scanning. And a run that changes what gets scanned cannot be matched against a candidate — the API exposes neither a scan's configured scan types and target policies nor whether it bundled a container image — so the flag is rejected alongside --scan-type, --policy, --include-image, --only-uncommitted, and --target.

--exclude is allowed, and warns on a skip. A reused scan is one of the whole commit (an --exclude upload is recorded as not matching the commit exactly, so it is never itself reusable), which means the results and the gate can cover files this run would have skipped — over-reporting, never under-reporting.

Dependency Inventory (offline)

corgea deps builds a dependency inventory from npm, Python, and Java manifests and lockfiles, then evaluates a pinning policy (DEP rules). Runs fully offline — no token or network required.

corgea deps scan                       # table report for the current directory
corgea deps scan --format agent        # compact TSV for coding agents
corgea deps scan --format json         # JSON inventory on stdout
corgea deps scan --format quiet        # no stdout; exit code still applies
corgea deps scan --fail-on high        # exit 1 if any finding is >= high
corgea deps scan --out-format json     # machine-readable (json or sarif)
corgea deps graph --format json        # print the resolved dependency graph
corgea deps explain <package> --format agent  # show why a package is present
corgea deps diff --base origin/main --format json
corgea deps sbom --format cyclonedx    # emit a CycloneDX SBOM
corgea deps policy init --exist-ok     # write starter policy, or keep existing file

corgea deps defaults to --format agent when an agent environment is detected (AI_AGENT, CODEX_SANDBOX, CLAUDECODE, and related agent variables). Use --format human to force the normal terminal output.

See Dependency Scanning (CLI) for the full flag and exit-code reference.

Install Gate

Prefix a package-manager install with corgea to vet every package it would install — named and transitive — against Corgea's vulnerability API before anything lands on disk. Known-vulnerable or malicious versions block the install; a clean set runs the underlying command untouched. Works with pip, npm, yarn, pnpm, and uv.

No token required — baseline public CVE checks run out of the box. Try it:

corgea npm install [email protected]      # blocks: known-vulnerable (CVE-2025-13465), exits 1
corgea pip install requests            # resolves, checks the verdict, then runs pip
corgea npm install axios@^1.0.0        # ranges resolve to a concrete version first
corgea pip --force install <pkg>       # print findings but install anyway
corgea pip list                        # non-install subcommands pass straight through

corgea pip install and corgea npm install resolve the full would-install set (named + transitive) via a safe dry-run, so a vulnerable transitive dependency blocks too. Blocked findings steer to the fix: each advisory shows fixed in <version>, and the gate prints the safe version to install instead.

The gate also blocks freshly published packages — anything published within the recency window (default 14 days) — to catch just-shipped typosquats and hijacks before advisory feeds catch up. It is on by default; turn it off with recency_gate = false in ~/.corgea/config.toml, retune the window with recency_threshold_days, or pass --force for a one-off install.

Logging in (corgea login) upgrades the gate to authenticated enforcement — unverifiable packages, resolution errors, and lookup failures then fail closed (public mode warns and continues). Wrapper flags (--force, --json) go between the manager and its command: corgea npm --force install <pkg>.

See the CLI docs for the full flag and exit-code reference.

Development Setup

Prerequisites

• Python 3.8 or higher
• Rust toolchain (for maturin)

Using venv (Python Virtual Environment)

1. Create and activate a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Unix/macOS
   .venv\Scripts\activate     # On Windows

2. Install dependencies:

   pip install maturin

3. Build and install the package in development mode:

   maturin develop

Using Conda

1. Create and activate a conda environment:

   conda create -n corgea-cli python=3.8
   conda activate corgea-cli

2. Install dependencies:

   pip install maturin

3. Build and install the package in development mode:

   maturin develop

Note: After making changes to Rust code, you'll need to run maturin develop again to rebuild the package.