Skip to main content

​
Introduction

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 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.
Power up your AI coding agent. The Corgea CLI also serves as the foundation for our Agentic Integrations — install the Corgea Agent Skill and let your AI agent (Cursor, Claude Code, Copilot, and more) scan, triage, and fix vulnerabilities on your behalf.

​
Features

  • Multiple Scanner Support: Scan with BLAST (our AI-powered scanner), and upload reports from Semgrep, Snyk, Checkmarx, CodeQL, Fortify, and Coverity.
  • Issue Management: List, inspect, and manage security findings.
  • Fix Integration: View and apply AI-generated fixes for vulnerabilities right from your terminal.
  • Dependency Scanning: Build offline dependency inventories, inspect dependency graphs, generate SBOMs, and evaluate dependency policy with corgea deps.
  • Container Image Scanning: Scan fully built container images alongside your code with corgea scan --include-image.
  • Package Advisory Checks: Look up known advisories before selecting or installing an npm or PyPI package.
  • Package Manager Install Gate: Vet npm, yarn, pnpm, pip, and uv installs for known-vulnerable, malicious, or suspiciously fresh packages before they land — see Package Manager Install Gate.
  • Flexible Output: Support for both human-readable and JSON output formats for easier CI integrations.
  • CI/CD Integration: Fail builds based on severity levels or custom blocking rules.
  • Scan Management: Track scan progress and results across your projects.
  • Agent Skill Installation: Install approved agent skills from the Corgea registry into supported coding agents.

​
Prerequisites

  • Corgea account: An active Corgea account.
  • Token for authentication: A valid Corgea API token or JWT access token.
The offline corgea deps scan, graph, explain, diff, sbom, and policy init commands do not require a Corgea account, token, configuration, or network access.

​
Installation Guide

​
Install with npm

The npm package bundles native binaries for supported platforms and selects the correct binary for your OS and architecture at runtime.

​
Install with uv

For Python users, this is the preferred installation method. uv tool install creates an isolated tool environment from the PyPI package and exposes the CLI as corgea on your PATH.
If uv reports that its tool directory is not on your PATH, run:

​
Install with pip

If you do not use uv, you can install the Corgea CLI with Python’s package installer, pip:
This command fetches the Corgea CLI package from PyPI (Python Package Index) and installs it on your system. You can find more details about the package on its PyPI page: https://pypi.org/project/corgea-cli/.

​
Install with Homebrew

To install the Corgea CLI tool using Homebrew, first add the Corgea tap and then install the CLI:

​
Install Manually

Download the archive for your platform from the latest release, unzip it, and move the corgea binary onto your PATH. The latest/download URLs below always resolve to the most recent release.
The GNU Linux builds require glibc 2.17 or newer. Fully static musl builds with no libc requirement are also available for both architectures as corgea-x86_64-unknown-linux-musl.zip and corgea-aarch64-unknown-linux-musl.zip; use these for minimal containers and CI runners.

​
Authentication

​
Login with your cli

To authenticate with the CLI, use the following command. This will redirect you to the web application to authorize the CLI:

​
Login with custom scope (for customers with Single-Tenant Instance)

Hint: Your company scope is the Corgea subdomain, for example: https://your-company.corgea.app

​
Login with token (API token or JWT)

For automated pipelines and CI/CD environments, use token authentication for a reliable, non-interactive login flow. You can pass either a Corgea API token or a JWT access token:
You can also set the token in an environment variable:

​
Point To A Single-Tenant Instance

Customers using a single-tenant instance need to configure the CLI to point to their specific instance using the --url option:
You can also set the URL in an environment variable and the CLI will automatically detect it:

​
Usage

​
Commands and Options

​
Check Package Advisories

Use corgea advisories check to review known advisories before choosing or installing an npm or PyPI package. A package-only check lists its advisory history; add an exact version to get a verdict for that release.
The ecosystem can be npm or pypi (pip is also accepted as an alias). npm versions must use a complete, exact version such as 1.2.3; ranges, tags, and partial versions are not supported. PyPI checks accept either package@version or pip-style package==version syntax. Package-only results help you review advisory history before selecting a version. Exact-version results include known advisory details, fixed-version information when available, and a safe-version recommendation when all reported advisories have fixes. This command is read-only and requires network access; the package manager install gate remains the enforcement step. Use --json for a machine-readable schema version 1 response. The command exits with code 0 when no advisories are found, 1 when advisories are found, and 2 for an error. A package not present in the advisory database exits with code 0.

​
Package Manager Install Gate

Use corgea npm, corgea yarn, corgea pnpm, corgea pip, or corgea uv to run supported package-manager install commands through Corgea before dependencies are installed.
Corgea checks each resolved version for known-vulnerable or malicious releases against public vulnerability data — no token required — and blocks unusually fresh releases (see Recency gate below). Vulnerable, malicious, or too-recent versions block the install before the package manager runs. Place wrapper flags between the manager name and its command, for example corgea pip --force install requests. Recency gate. Beyond vulnerability data, Corgea blocks any named install target whose resolved version was published within a recency window — catching just-shipped typosquats and hijacks before advisory feeds catch up. It is on by default with a 14-day window. Configure it in ~/.corgea/config.toml (recency_gate = false to disable, recency_threshold_days to retune the window), or with the CORGEA_RECENCY_GATE and CORGEA_RECENCY_THRESHOLD_DAYS environment variables. Packages whose publish date can’t be determined never trip the gate, a vulnerable or malicious verdict takes precedence over freshness, and --force bypasses it for a single install. Coverage. pip install and npm install resolve the full would-install set, including transitive dependencies, so a vulnerable transitive dependency blocks the command; if the dry-run resolver fails, Corgea warns and falls back to named-target checks. npm ci is gated from the project lockfile and uv sync from uv.lock, so the full locked set is checked even though those commands name no packages. The uv gate also covers named uv add ... and uv pip install ... targets, while uv lock passes through because it installs nothing. yarn and pnpm check named targets only — they have no safe dry-run resolver. Bare installs. Bare npm install is gated from the project’s package.json. Bare yarn, pnpm, and install-shaped uv commands cannot be checked first, so Corgea prints a note and runs them unchecked.
Public vs authenticated. Without a token the gate runs in public mode: vulnerable and malicious packages still block, but unverifiable packages and lookup failures only warn and let the install continue (repeated failures collapse into one summary line). With a token from CORGEA_TOKEN or corgea login on the default vulnerability API, the gate runs in authenticated mode and fails closed — unverifiable packages, dependency-resolution failures, vulnerability-API outages, and degraded tree coverage on managers that normally resolve the full tree (pip, npm, uv) block the install unless you pass --force. Custom vulnerability API. If you point CORGEA_VULN_API_URL at a custom endpoint, Corgea does not send your token there, so the gate stays in public mode. Set CORGEA_VULN_API_SEND_TOKEN_TO_CUSTOM_URL=1 to enable authenticated enforcement against an endpoint you trust. Externally managed Python. For pip, Corgea refuses installs into externally managed environments (PEP 668) before registry checks run. Activate a virtual environment, or pass --force to bypass. Corgea runs the matching package manager from your PATH. For corgea pip ..., it tries pip3 when pip is missing; if neither exists, the CLI exits 127 and names the missing binary. Non-install commands and flags are forwarded to the package manager. For example, corgea npm --version reports the installed npm version, while corgea --version reports the Corgea CLI version. Findings. When a resolved package is vulnerable, tree findings show its origin:
  • (from requirements) — requested through a pip requirements file.
  • (already in package.json) — already a direct npm dependency.
  • (transitive) — pulled in through another dependency.
When the named package is clean but the resolved tree already contains a vulnerable package, the refusal identifies the existing tree as the source. Advisory lines show the advertised fixed version, or that none is known; when every advisory on a package has fix data, Corgea prints safe version: axios@0.21.2, and for vulnerable direct npm dependencies it may print fix with: corgea npm install package-name@version (advertised fix). Vulnerability counts and exit behavior follow the original install target. JSON output. --json returns one report on stdout and writes resolution and package-check progress to stderr, keeping stdout available for machine-readable output. The package manager’s stdout is also redirected to stderr. Schema version 2 reports manager, subcommand, args, recency_threshold_days (the active recency window, or null when the gate is off — pair it with each result’s age_seconds), a summary split into named and tree counts, verdict_mode, a results array, and a tree object when tree resolution ran. Tree entries carry an origin of requested, pre-existing, or transitive. Known-malicious packages report a distinct verdict status of malicious, a per-match malware boolean, and a separate malicious count in each summary object. Their remediation is always null because the package should be removed rather than upgraded; vulnerable verdicts continue to report a safe version only when it covers every advisory.

​
Install Agent Skills

Install an approved skill from the Corgea registry into your coding agent’s skills directory:
Supported agent IDs are cursor, claude-code, codex, github-copilot, gemini-cli, windsurf, opencode, and universal. Use --scope project to install into the current repository, --scope user to install for your user account, or --dir to install into a custom skills directory. To install a specific version, append it to the skill name:
You can also save a default agent for future installs:
You can also save the default while installing by adding --set-default, which persists the --agent value you passed:
The CORGEA_DEFAULT_AGENT environment variable overrides the saved default, which is useful in CI where you do not want to write to the config file.

​
Upload a Scan Report

Upload a scan report to Corgea via STDIN or a file (JSON, SARIF, FPR, or Coverity XML):
To control the project name shown in Corgea for uploaded reports, use --project-name. If omitted, the CLI defaults to the git repository name when available, and falls back to the current directory name.
By default, the command returns after upload and prints the scan page URL. Add --wait to wait for processing to finish and print the results:
For large reports, the CLI uploads data in chunks. During chunked uploads, the CLI verifies server upload progress and exits with a non-zero status if the server reports an unexpected offset or if the upload completes without returning a scan ID.

​
Scan Your Codebase

To scan your current directory using the default BLAST scanner:
The CLI detects uncommitted changes in your working tree. Scans that include these changes run as full scans so the results reflect the files you uploaded, even when the current commit SHA has not changed. To specify a different scanner, such as Semgrep:
You can also use --fail-on (BLAST scans only) with one or more comma-separated conditions: CR, HI, ME, LO, or malicious. Severity conditions match findings at that severity or higher; for example, ME also matches HI and CR findings. The malicious condition matches a dependency finding classified as malicious. The command exits with a non-zero status when any listed condition matches. Examples:
For example, --fail-on ME fails on ME, HI, or CR findings. When multiple conditions are listed, the scan fails if any condition matches. A vulnerable dependency that is not classified as malicious does not match the malicious condition. Or fail based on every active blocking rule defined in the web app, regardless of whether each rule applies to pull requests or CI:
--fail is deprecated in CLI 1.10.0 and later. Prefer --block-on to name the CI rules a pipeline should enforce. To enforce specific rules in a CI pipeline, set each rule’s Applies To target to CI in the web app and pass the generated slug to --block-on (CLI 1.10.0 or later):
You can provide multiple slugs as a comma-separated list, for example criticals,malicious-deps. Only active CI rules can be used; an unknown slug, inactive rule, or pull request rule causes the command to fail with a configuration error. --block-on is supported only by the BLAST scanner and cannot be combined with --fail or --fail-on. --fail and --fail-on also cannot be used together. Blocking rules are evaluated in the Corgea cloud, so the command waits for that to finish — up to 15 minutes. If the wait runs out it exits 1 rather than letting an unevaluated scan through. Set CORGEA_BLOCKING_RULES_TIMEOUT_SECONDS to the number of seconds to wait instead:
A scan that trips a blocking rule still writes any --out-file report and --sbom output before exiting. By default, the scan command scans the entire project. However, if you only want to scan your changes before committing, you can use the —only-uncommitted option.
You can also target specific files or subsets of your project (BLAST scans only) with the --target option. This accepts comma-separated values and supports file paths, directory paths, glob patterns, git selectors, or stdin. Examples:
You can exclude files from BLAST scans with the --exclude option. This accepts comma-separated glob patterns and can be used with or without --target.
Note: --only-uncommitted and --target cannot be used together. To skip files during a BLAST scan, use --exclude with comma-separated glob patterns. It can be combined with --target to scan a subset while excluding matches within it.
To control the project name shown in Corgea, use --project-name. If omitted, the CLI defaults to the git repository name when available, and falls back to the current directory name.
To attach custom metadata to a BLAST scan, repeat --metadata with KEY=VALUE pairs. These values are included with the scan and in JSON scan-list output.
--metadata is supported only by the BLAST scanner. Each entry must have a non-empty key; if the same key is supplied more than once, the last value is used. In the Corgea web app, scan metadata appears as read-only labels on the Scans page, scan details, and issue details.
Scans page showing read-only scan metadata chips on each scan
Scan details header showing scan metadata chips
Issue details sidebar showing scan metadata chips
On the Scans page, expand the filters to filter by a metadata key, an exact key and value, or a value across all metadata.
Scans page filter panel with Scan metadata key and value fields
The main search also accepts has:key and key:value, for example has:pipeline_url or environment:production.
Scans search filtered with has:version
The regular BLAST scan includes multiple scans:
  • Blast Base AI Scan
  • PolicyIQ Scan
  • Malicious Code Detection Scan
  • Secrets Detection Scan
  • Personally identifiable information (PII) Detection Scan
By default, all these scans run (if they are enabled for your company account plan). However, the CLI provides the flexibility to run a scan targeting one or more types with the —scan-type option.
or multiple types
To target specific policies with a policyIQ scan, use the —policy option. This allows you to focus on one or more policies by passing their ID(s).
--scan-type and --policy apply only to BLAST scans. Passing --policy without --scan-type policy still runs the other BLAST scan types and prints a warning.

​
Scan Container Images

By default, Corgea discovers the images your project references in Dockerfile and Docker Compose files. To scan a fully built image instead — for example one you just built in CI that has never been pushed to a registry — pass it with --include-image:
The flag is repeatable, so you can include several images in one scan:
Each image is exported by your local container engine and uploaded with your project, so it is scanned exactly as it ships. When you pass --include-image, Corgea scans the images you provide instead of searching your source tree for base images. Requirements and behavior:
  • Container scanning must be enabled for your account.
  • docker or podman must be available on your PATH. Corgea uses whichever it finds first; set CORGEA_CONTAINER_ENGINE to choose explicitly.
  • An image that is not available locally is pulled first, so images from a private registry work as long as your container engine is already authenticated to it.
  • --include-image is supported only by the BLAST scanner.
See Container Image Scanning for how container findings are reported and tracked.

​
Export Scan Report

The Corgea CLI allows you to export scan results to a file, which is particularly useful when running the tool within a CI pipeline. You can do this using the —out-format and —out-file options.
The CLI currently supports HTML, JSON, SARIF, and Markdown as output formats.
For BLAST scans, add --sbom to generate a CycloneDX SBOM after the scan completes. The default file is bom.json, or you can provide a path:
Reports and SBOMs are written before --fail and --block-on are evaluated. A scan that exits with a non-zero status because a blocking rule tripped still leaves its report and SBOM on disk, so a later CI step can always ingest them.

​
Reuse a Recent Scan of the Same Commit

A pipeline that re-runs on an unchanged commit can reuse the scan Corgea already has instead of paying for a duplicate. Add --skip-if-commit-scanned-recently to a BLAST scan:
When the project already has a completed scan of the current commit inside the reuse window, 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. The pipeline behaves the same whether or not a scan actually ran. Use --scanned-within to set the window. It is only valid with --skip-if-commit-scanned-recently. It accepts values such as 90s, 30m, 24h, and 7d, and reads a bare number as hours. The default is 24h, because unchanged code is still exposed to advisories published since it was last scanned.
To reuse a recent scan even when this worktree is dirty, or when the prior scan recorded worktree_dirty=true, pass --ignore-dirty-worktree (CLI 1.11.1 or later). It can only be used with --skip-if-commit-scanned-recently. A new scan still reports the real dirty status to Corgea.
So a later step can tell the two outcomes apart, the command prints CORGEA_SCAN_SKIPPED=true along with CORGEA_SCAN_ID=<id> when it reused a scan, and CORGEA_SCAN_SKIPPED=false when a scan ran. These lines are stdout markers, not environment variables. They are not printed if the command exits because the current commit cannot be resolved. If the reuse check cannot reach the API, the CLI warns and runs a new scan. What can be reused. Corgea only reuses a scan that answers the same question, which is stricter than matching the commit. A candidate must be a completed BLAST scan of the current commit, run on a branch rather than a pull request, from a clean worktree, with no scanner problems reported. Anything else runs a real scan — nothing inside the window, a failed or still-running scan, or a worktree that does not match the commit. --ignore-dirty-worktree overrides the dirty-worktree half of that test: reuse proceeds if this worktree is dirty or the prior scan recorded worktree_dirty=true. A prior scan that never reported the flag is still not reused, because its scope is unknown. Options that cannot be combined. No API reports how an earlier scan was scoped, so --skip-if-commit-scanned-recently cannot be combined with --only-uncommitted, --target, --scan-type, --policy, or --include-image, and the command fails if you pass one of them. --exclude is allowed but prints a warning when a scan is reused: the reused scan covers files this run would have skipped, so results can over-report, never under-report. If the current commit cannot be resolved — the directory is not a git repository, or the repository has no commits yet — the command exits with a non-zero status instead of silently running a full scan. When a scan is reused, --sbom still reflects the current workspace rather than the reused scan’s earlier SBOM.

​
Dependency Inventory

Use corgea deps to build an offline dependency inventory from npm, Python, and Java manifests and lockfiles. The command evaluates dependency pinning policy, can fail CI based on findings, and does not require login or network access.
Common dependency inventory commands:
Use --format human, agent, json, or quiet to control terminal output for scan, graph, explain, diff, and policy init. In detected agent environments, corgea deps defaults to the compact agent format; pass --format human to force normal terminal output. For corgea deps scan, use --out-format table, json, or sarif with optional --out-file when exporting a report. Do not combine --format and --out-format on the same deps scan command. To customize dependency policy, initialize .corgea/deps.yml:
The generated policy controls whether lockfiles are required, missing or stale lockfiles fail, and direct dependencies using wildcards, latest, or semver ranges are reported. See Dependency Scanning for CI examples, policy configuration, and troubleshooting.

​
Wait for a Scan

To wait for the latest in-progress scan:
Or specify a scan ID to wait for:
corgea wait, corgea scan, and corgea upload --wait exit 1 if the scan fails, printing the reason and any scanners that reported a problem. A scan that finishes with one scanner’s results missing exits 0 with a warning. Waiting stops after 10 hours, so a scan that never reports a final status cannot hold a CI job open indefinitely. On timeout the command exits with code 1. The scan itself keeps running in the Corgea cloud. If your scans need longer, set CORGEA_SCAN_TIMEOUT_SECONDS to the number of seconds to wait:
The CLI normally resolves the project from the current repository’s remote URL. Use --repo org/repo (or a repository URL) to resolve a different repository, or --project-name to query an exact Corgea project name. If you already know both IDs, corgea wait SCAN_ID --project-id PROJECT_ID skips project resolution. corgea scan, corgea wait, and corgea upload --wait all exit with a non-zero status when a scan fails, printing the reason and naming any scanners that hit problems. A scan that completes with a scanner missing exits 0 with a warning instead. Waiting gives up after 10 hours; set CORGEA_SCAN_TIMEOUT_SECONDS to change that budget. When --fail or --block-on is used, the CLI then waits up to 15 minutes for blocking rules to be evaluated; set CORGEA_BLOCKING_RULES_TIMEOUT_SECONDS to change that one.

​
List Scans, Security Issues, SCA Issues, or Code Quality Issues

To list all scans for a current directory (paginated by default):
To list issues for a specific scan:
You can also control the pagination:
Note: The --json option is available for commands like list and inspect to output results in JSON format, which is useful for integrations and automation.
The scan table includes the first eight characters of each scan’s commit SHA, or N/A when no SHA is available. JSON output includes the complete git_sha value, the nullable worktree_dirty value, and any scan metadata returned by Corgea. worktree_dirty is true when the scan included uncommitted local changes and can be null for scans created by older CLI versions. To list SCA issues for a project or scan, use --sca-issues or the -c shorthand. The table includes each issue’s classification, and JSON output includes the classification field when provided.
or
To list code quality issues, use --code-quality (or --quality/-q). Like the other issue modes, it can be limited to a scan with --scan-id.
List commands resolve the current project from the repository remote. Use --repo org/repo (or a repository URL) to select another repository, or --project-name to query an exact Corgea project name.

​
Inspect a Scan or Issue

To inspect a specific scan:
To inspect issues with detailed output:
For fix explanations or diffs:

​
Integrating with GIT Hooks

To ensure code quality and security, you can integrate Corgea CLI with your Git workflow using pre-commit hooks. This feature allows you to scan your code changes before committing or pushing them. To set up the pre-commit hook, simply run
When setting up the pre-commit hook, you will be prompted to enter your preferred configurations for the scan. To quickly set it up with the default settings, which include scan types for PII and secrets, and fail levels set to CR, HI, ME, and LO, you can run
To bypass the pre-commit check when committing, use the following command:

​
Environment Variables

​
Debug Mode

To enable debug logs, set CORGEA_DEBUG=1 before running a command.
When debug mode is enabled, failed upload requests include the HTTP status and response body in debug output, which helps with troubleshooting.

​
Additional Options

For more options and commands, use:

​
Release Notes

For full release notes, please visit our GitHub releases page.