AEGIS CLI

Command-line scanner.

Usage

aegis [path] [options]
aegis --code "eval(x)" [--file-path app.py]
aegis --repo <url> [--branch main] [--scan-history]
aegis dynamic <target> [--scan-mode standard] [--instruction ...] [--push --aegis-url URL --api-key KEY]
aegis install-hook [--fail-on high] | uninstall-hook

Specify only one of a path, --code, or --repo (exit 2: Specify only one of a path, --code, or --repo).

Options

FlagDescription
pathDirectory or file to scan. Leading/trailing spaces are stripped. A blank path with other flags exits 2 (Specify a path, --code, or --repo to scan)
--code <str>Scan a code snippet from the command line
--file-path <name>Filename label for --code so Docker/notebook/IaC routing applies. Requires --code (exit 2: --file-path requires --code). Blank labels exit 2 (--file-path cannot be blank)
--repo <url>Clone and scan a git repository. Blank URLs exit 2 (--repo cannot be blank). Must be http:// or https:// (exit 2: --repo must be http:// or https:// (github.repositoryUrl is git:// and is rejected))
--branch <name>Git branch for --repo clone (default: main). Requires --repo (exit 2: --branch requires --repo). Blank names exit 2 (--branch cannot be blank)
--scan-historyAlso scan git commit history for committed secrets. Requires a path or --repo. Exits 1 if git is unavailable, the path is not a git repository, or git log / git show fails or times out (Cannot scan git history)
--max-commits <n>Limit history scan depth (default: 200, max 500). Requires --scan-history (exit 2: --max-commits requires --scan-history). Out of range exits 2 (--max-commits must be between 1 and 500)
--format <fmt>Output format: json, sarif, csv, md, aibom (default: json). aibom is a CycloneDX 1.6 AI bill of materials (models, datasets, AI providers, MCP servers) and needs a directory or --repo scan. Values are case-insensitive (SARIF → sarif). Without --output, non-json formats write to stdout. Banner and clone progress go to stderr so a piped document stays parseable. Format failures exit 1 (Cannot export). Combined with --json, non-json formats need --output
--jsonPrint JSON on stdout. Banner and clone progress go to stderr unless --quiet. --format json alone prints the human summary. Combined with --format sarif / csv / md requires --output (exit 2: --json cannot be combined with --format unless --output is set)
--output <path>Write results to file. Blank paths exit 2 (--output cannot be blank). Leading/trailing spaces are stripped so .sarif / .xml checks still apply. Write failures exit 1 (Cannot write). A .sarif / .csv / .md / .cdx.json filename requires matching --format (exit 2: --output of a .sarif file requires --format sarif). --format sarif with a non-.sarif path exits 2 (--format sarif requires a .sarif --output) so upload-sarif still finds the file. JUnit / HTML / PDF / CodeClimate / the full CycloneDX SBOM are HTTP export only (exit 2: --output of a .xml file is not a CLI format)
--fail-on <sev>Exit non-zero if findings at this severity or above. Values are case-insensitive (HIGH → high). Defaults to gate.fail_on in .aegis.yml
--baseline <file>SARIF or JSON report from an earlier scan. Only findings not in it count toward --fail-on; JSON marks baseline_state and SARIF sets baselineState. Defaults to gate.baseline in .aegis.yml. A missing or unreadable file exits 2
--config <file>Repository configuration to use instead of the scanned directory's .aegis.yml (rules, severities, gate). An invalid file exits 2
--verbosePrint finding details. Cannot be combined with --json (exit 2: --verbose cannot be combined with --json). Combined with --format sarif / csv / md requires --output (exit 2: --verbose cannot be combined with --format unless --output is set). Does not apply to install-hook / uninstall-hook (exit 2: --verbose does not apply to install-hook or uninstall-hook)
--quietSuppress banner, clone progress, the Exported: line, and Pushed: (those already go to stderr). Without --fail-on / --json / --output / non-json --format, findings still print so a quiet scan cannot look clean. With --fail-on, stdout stays empty and FAILED goes to stderr
--pushAfter dynamic, POST findings to /api/scan/import. Success prints Pushed: on stderr so --json stdout stays parseable. Blank or missing --aegis-url / --api-key (after spaces are stripped) exit 2 before Strix runs (--push needs --aegis-url and --api-key (or AEGIS_URL / AEGIS_BASE_URL / AEGIS_API_KEY)). Invalid URLs exit 2 (AEGIS base URL must be https, or http://localhost / 127.0.0.1 / [::1])
--scan-modeStrix depth for aegis dynamic only (quick, standard, deep). Values are case-insensitive (DEEP → deep). Requires aegis dynamic even when the value is standard
--instructionExtra Strix directive. Only with aegis dynamic
--aegis-url <url>AEGIS base URL for --push (env AEGIS_URL or AEGIS_BASE_URL). Requires --push (exit 2: --aegis-url requires --push). Leading/trailing spaces are stripped so a padded https URL still passes the allowlist
--api-key <key>API key for --push (needs the scan:write scope). Requires --push (exit 2: --api-key requires --push). Leading/trailing spaces are stripped

Subcommands

SubcommandDescription
install-hookInstall git pre-commit hook. --fail-on sets the default threshold (AEGIS_FAIL_ON still overrides). The hook exits 1 if aegis is not on PATH, or if it cannot read staged files. --json / --format / --output do not apply (exit 2: --json, --format, and --output do not apply to install-hook or uninstall-hook)
uninstall-hookRemove the pre-commit hook. Does not accept --fail-on (exit 2: --fail-on does not apply to uninstall-hook), --json, --format, or --output (exit 2: --json, --format, and --output do not apply to install-hook or uninstall-hook)
dynamic <target>Run Strix locally (needs Docker + STRIX_LLM). Blank or padded target exits 2 (usage: aegis dynamic <path-or-url>) before Strix runs. HTTP POST /api/scan/dynamic is the worker path and needs AEGIS_ENABLE_DYNAMIC_SCANS=1

Exit Codes

CodeMeaning
0Scan completed; no findings at or above --fail-on threshold
1Findings at or above --fail-on, a scan error, no scannable files in a directory / --repo, a file that cannot be read (Cannot read), --scan-history when git is unavailable, the path is not a git repository, or git log / git show fails or times out (Cannot scan git history), a format failure (Cannot export), or a human-summary failure (Cannot print results)
2Usage error (missing path / --code / --repo, more than one of a path / --code / --repo (Specify only one of a path, --code, or --repo), blank --code, --file-path without --code, blank --file-path (--file-path cannot be blank), blank --repo (--repo cannot be blank), git:// / non-http(s) --repo (--repo must be http:// or https:// (github.repositoryUrl is git:// and is rejected)), blank --output (--output cannot be blank), --branch without --repo, blank --branch (--branch cannot be blank), --max-commits without --scan-history (--max-commits requires --scan-history), --max-commits outside 1–500 (--max-commits must be between 1 and 500), --aegis-url / --api-key without --push, --push with a blank or invalid --aegis-url / --api-key (--push needs --aegis-url and --api-key (or AEGIS_URL / AEGIS_BASE_URL / AEGIS_API_KEY)), --json with --format sarif / csv / md unless --output is set (--json cannot be combined with --format unless --output is set), --json / --format / --output on install-hook / uninstall-hook (--json, --format, and --output do not apply to install-hook or uninstall-hook), --fail-on on uninstall-hook (--fail-on does not apply to uninstall-hook), a .sarif / .csv / .md --output without matching --format (--output of a .sarif file requires --format sarif), JUnit / HTML / PDF / CodeClimate / CycloneDX --output (--output of a .xml file is not a CLI format), --verbose with --json (--verbose cannot be combined with --json), --verbose with --format sarif / csv / md unless --output is set (--verbose cannot be combined with --format unless --output is set), --verbose on install-hook / uninstall-hook (--verbose does not apply to install-hook or uninstall-hook), missing dynamic target, --push / --scan-mode / --instruction without aegis dynamic (including --scan-mode standard), or --scan-history without a path / --repo)