Command-line scanner.
| Flag | Description |
path | Directory 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-history | Also 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 |
--json | Print 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 |
--verbose | Print 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) |
--quiet | Suppress 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 |
--push | After 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-mode | Strix depth for aegis dynamic only (quick, standard, deep). Values are case-insensitive (DEEP → deep). Requires aegis dynamic even when the value is standard |
--instruction | Extra 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 |
| Subcommand | Description |
install-hook | Install 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-hook | Remove 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 |
| Code | Meaning |
| 0 | Scan completed; no findings at or above --fail-on threshold |
| 1 | Findings 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) |
| 2 | Usage 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) |