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 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 PIP

To install the Corgea CLI tool, you can use Python’s package installer, pip. Open your terminal and run the following command:
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.
A statically linked Linux build is also published as corgea-x86_64-unknown-linux-musl.zip.

​
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

​
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 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. 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 redirects the package manager’s stdout to stderr so Corgea owns stdout. The report includes schema_version, 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; vulnerable verdicts carry remediation with the safe version covering every advisory, or null when any advisory has no known fix.

​
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.
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:
To specify a different scanner, such as Semgrep:
You can also set the CLI to fail on a specific severity level:
Or fail based on blocking rules defined in the web app:
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.
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 multipe 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.

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

​
List Scans, Issues or SCA 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.
To list SCA for a project or a scan use --sca-issues or ‘-c’ shorthand
or

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