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.
  • 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:

​
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. The CLI waits for blocking-rule evaluation to finish before returning. If evaluation does not complete within 15 minutes, the scan fails closed with a non-zero exit status. 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).

​
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:

​
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:
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.

​
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:

​
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.