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

npm install -g @corgea/cli
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: 
pip install corgea-cli
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: 
brew tap Corgea/cli
brew install corgea-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. 
curl -L https://github.com/Corgea/cli/releases/latest/download/corgea-aarch64-apple-darwin.zip -o corgea.zip && unzip corgea.zip
chmod +x corgea
sudo mv corgea /usr/local/bin
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: 
corgea login

​
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 
corgea login --scope your-company

​
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: 
corgea login YOUR_TOKEN
You can also set the token in an environment variable: 
export CORGEA_TOKEN="your-token-here"
corgea login

​
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: 
corgea login --url https://<<Your Instance>>.corgea.app YOUR_TOKEN
You can also set the URL in an environment variable and the CLI will automatically detect it: 
export CORGEA_URL="https://<<Your Instance>>.corgea.app"
export CORGEA_TOKEN="your-token-here"
corgea login

​
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 npm install axios@0.21.0
corgea yarn add lodash
corgea pnpm install express
corgea pip install requests==2.31.0
corgea uv add requests
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.
FlagDescription
--forceProceed despite any finding (vulnerable, malicious, unverifiable, or too-recent). Also bypasses pre-flight refusals: a detected wrong package manager and externally managed Python environments.
--jsonEmit one machine-readable report (with verdict_mode as public or authenticated) instead of human-readable text (see below).
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. 
corgea npm install
corgea yarn install
corgea pnpm install
corgea uv add
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: 
corgea skill install corgea --agent cursor --scope user
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: 
corgea skill install corgea@1.0.0 --agent cursor --scope user
You can also save a default agent for future installs: 
corgea skill set-default-agent cursor
corgea skill install corgea --scope user

​
Upload a Scan Report

Upload a scan report to Corgea via STDIN or a file (JSON, SARIF, FPR, or Coverity XML): 
corgea upload path/to/report.json
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. 
corgea upload path/to/report.json --project-name my-service
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: 
corgea scan
To specify a different scanner, such as Semgrep: 
corgea scan semgrep
You can also set the CLI to fail on a specific severity level: 
corgea scan --fail-on CR
Or fail based on blocking rules defined in the web app: 
corgea scan --fail
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. 
corgea scan --only-uncommitted
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: 
corgea scan --target src/,pyproject.toml

corgea scan --target "src/**/*.py"

corgea scan --target git:diff=origin/main...HEAD

corgea scan --target git:staged,git:modified,git:untracked

corgea scan --target -

git ls-files -z | corgea scan --target -0
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. 
corgea scan --exclude "tests/**,**/*.test.ts"

corgea scan --target "src/" --exclude "**/*.md,**/*.spec.js"
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. 
corgea scan --exclude "tests/**,**/*.spec.js"
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. 
corgea scan --project-name my-service
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. 
corgea scan --scan-type secrets
or multipe types 
corgea scan --scan-type blast,malicious,policy,secrets,pii
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). 
corgea scan --scan-type policy --policy 1

​
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. 
corgea scan --out-format=json --out-file=report.json
The CLI currently supports HTML, JSON, SARIF, and Markdown as output formats. 
corgea scan --out-format=html --out-file=report.html

corgea scan --out-format=sarif --out-file=report.sarif

​
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. 
corgea deps scan
Common dependency inventory commands: 
corgea deps scan --format human
corgea deps scan --format json
corgea deps scan --format quiet --fail-on high
corgea deps scan --out-format sarif --out-file deps.sarif
corgea deps graph --format json
corgea deps explain lodash --format human
corgea deps diff --base origin/main --format json
corgea deps sbom --format cyclonedx --out bom.json
corgea deps policy init --exist-ok
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: 
corgea deps policy init
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: 
corgea wait
Or specify a scan ID to wait for: 
corgea wait SCAN_ID

​
List Scans, Issues or SCA Issues

To list all scans for a current directory (paginated by default): 
corgea ls
To list issues for a specific scan: 
corgea ls --issues --scan-id SCAN_ID
You can also control the pagination: 
corgea list --page 1 --page-size 10
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. 
corgea list --page 1 --page-size 10 --json
To list SCA for a project or a scan use --sca-issues or ‘-c’ shorthand 
corgea list --sca-issues --page 1 --page-size 10 --json
or 
corgea list -c --page 1 --page-size 10 --json

​
Inspect a Scan or Issue

To inspect a specific scan: 
corgea inspect SCAN_ID
To inspect issues with detailed output: 
corgea inspect --issue --json --summary ISSUE_ID
For fix explanations or diffs: 
corgea inspect --issue --fix ISSUE_ID
corgea inspect --issue --diff ISSUE_ID

​
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 
corgea setup-hooks
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 
corgea setup-hooks --default-config
To bypass the pre-commit check when committing, use the following command: 
git commit --no-verify

​
Debug Mode

To enable debug logs, set CORGEA_DEBUG=1 before running a command. 
CORGEA_DEBUG=1 corgea scan
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: 
corgea --help

​
Release Notes

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