CLI Reference

`argus tools`

Manages the scanner tools argus depends on. Install method is auto-detected per tool (go install / brew / pip / uv / apt / dnf) based on platform and how each tool is already installed.

argus tools check    # show which tools are installed and their versions
argus tools install  # install any tools that are missing
argus tools update   # upgrade installed tools to their latest versions

Tools managed: Go compiler, golangci-lint, staticcheck, gosec, govulncheck, semgrep, nilaway, deadcode, scc.

tools check — no-op dry view. Lists each tool with its detected version or “not installed”.
tools install — installs missing tools using: go install for Go tools (cross-platform), brew on macOS when the tool is brew-managed, pip3/uv for semgrep, or apt/dnf on Linux.
tools update — upgrades tools using the same method each was installed with: Go tools via go install @latest, brew-managed tools via brew upgrade, Python tools via pip3 install --upgrade or uv tool upgrade.

`argus init`

Generates a starter config.yaml with commented defaults.

argus init [flags]

Flag	Default	Description
`-o, --output`	`config.yaml`	Output file path
`-f, --force`	`false`	Overwrite existing file

`argus run`

Runs all configured scanners against the source tree. Each invocation creates a run tracked with timestamps, code statistics, and config. Successive runs accumulate in the same database for trend analysis.

argus run --src <path> --config <config.yaml> [flags]

Flag	Default	Description
`--src`	(required)	Root of the source tree to scan
`--config`	`config.yaml`	Path to the YAML configuration file
`--db`	`argus.db`	Path to DuckDB database file
`--name`	source dir name	Human-readable name for this run
`--timestamp`	now	Run timestamp as `YYYYMMDDTHH:MM:SS`
`--workers`	auto	Concurrent scan workers. 0/omit = auto (`min(NumCPU/2, 12)`). Overrides `workers:` in config
`--dry-run`	`false`	Show scan plan without running scanners
`-v, --verbose`	`false`	Verbose output

`argus snapshot create`

Materializes every configured repo as a git worktree checked out to a resolved commit. The resulting directory can be scanned with argus run as if it were a normal source tree.

argus snapshot create --src <path> --config <file> --name <name> [--date | --tag | --commit <value>] [flags]

Flag	Default	Description
`--src`	(required)	Source tree root
`--config`	`config.yaml`	Config YAML for inclusions/exclusions/aliases
`--name`	(required)	Snapshot name — becomes the directory name
`--out`	`.argus/snapshots`	Parent directory for snapshots
`--date`	—	ISO date (YYYY-MM-DD) — last commit on or before this date
`--tag`	—	Git tag to check out in every repo
`--commit`	—	Git commit/ref to check out in every repo
`--dry-run`	`false`	Print resolved repo→commit map without creating worktrees

Exactly one of --date, --tag, or --commit is required. A manifest file .argus-snapshot.yaml is written into the snapshot directory for later destroy operations.

`argus snapshot destroy`

Tears down worktrees created by snapshot create and removes the snapshot directory.

argus snapshot destroy --path <snapshot-dir>

Flag	Default	Description
`--path`	(required)	Path to snapshot directory

`argus reports`

Generates interactive HTML and PDF reports from scan data. Reports come in three audience-scoped flavors — pick the subcommand that matches who will read it:

argus reports customer [--runs <ids-or-names> | --last <N> | --latest] [flags]
argus reports internal [--runs <ids-or-names> | --last <N> | --latest] [flags]
argus reports dev      [--runs <ids-or-names> | --latest] [--repos …] [--severity …] [flags]

Subcommand	Audience	Content
`customer`	External stakeholders	Aggregate dashboard only. Run IDs, ruleset/toolchain hashes, `src_root`, file paths, line numbers, and sample messages are scrubbed from both the template and the embedded JSON payload. Safe to forward outside kis.ai.
`internal`	Engineering leads	Same aggregate dashboard as `customer` plus methodology footer (run ID, profile version, ruleset hash, toolchain hash, `src_root`) and sample messages on every top-rule row.
`dev`	Developers fixing findings	Flat, filterable, sortable per-finding table scoped to a single run. Each row carries repo, group, tool, rule, severity, category, file path relative to the repo, line number, message, CWE, and a syntax-highlighted code snippet (expand on click in the HTML view). Ships as HTML + XLSX by default — the XLSX has Summary / Findings / Profiles sheets with an auto-filter and frozen header row so you can sort, filter, and share findings in Excel.

Mode for customer / internal is inferred from how many runs resolve — 1 → summary, 2 → compare, 3+ → trend. dev is always single-run.

Shared flags (all three subcommands):

Flag	Default	Description
`--db`	`argus.db`	DuckDB path
`--runs`	—	Comma-separated run IDs or run names (the `--name` you passed to `argus run`), or the `latest` keyword. Resolution tries `run_id` first, falls back to an exact `name` match, and picks the most recent run when a name is ambiguous (with a logged warning).
`--last`	—	Use the last N completed runs (not available on `dev` — single-run only)
`--latest`	`false`	Shortcut for the most recent run
`--out`	`.argus/reports`	Output directory
`--format`	`both`	customer/internal: `html`, `pdf`, or `both` (both = html+pdf). dev: `html`, `xlsx`, or `both` (both = html+xlsx). PDF is not supported for dev reports — Chrome’s PrintToPDF fails on the multi-MB HTML a findings list produces, and XLSX is a better fit for filter/sort/share.
`--name`	auto	Filename prefix (default derived from audience + mode + run names)
`--title`	auto	Report title

Exactly one of --runs, --last, or --latest is required.

reports dev extra flags:

Flag	Default	Description
`--repos`	(all)	Comma-separated repo aliases, exact `source_repo` paths, or group prefixes (e.g. `lib`, `baas`). Groups expand to every repo under that top-level directory. Unmatched specs are logged as a warning.
`--severity`	(all)	Comma-separated subset of `critical,high,medium,low,info`.

reports customer extra flags:

Flag	Default	Description
`--config`	`config.yaml`	Path to the argus config that declares `projects.customer_visibility`.
`--customer`	`all`	Customer id to scope the report. Looks up `projects.customer_visibility.<id>` for include/exclude patterns and the display-alias map. Unknown id fails with the list of configured customers. Omitting the flag uses the `all` entry.

Output format.

HTML is a single self-contained file — all CSS, JavaScript, Chart.js (aggregate reports), highlight.js + atom-one-dark theme (dev reports), and scan data are inlined via Go’s embed.FS. No network access required.
PDF (customer / internal only) is rendered from the same HTML via headless Chrome (chromedp) — Chrome or Chromium must be on PATH. Print CSS swaps the dark on-screen theme for a light palette so charts and typography render cleanly on paper.
XLSX (dev only) is produced by xuri/excelize — no headless browser involved. The workbook has three sheets:
- Summary — run name, customer, product, profile, ruleset/toolchain hashes, severity counts, tool counts.
- Findings — one row per finding; columns: Severity · Repo · Group · Tool · Rule ID · Rule Title · Category · CWE · File · Line Start · Line End · Message · Language · Snippet. Severity cell is color-coded; auto-filter is enabled on the whole range and the header row is frozen.
- Profiles — profile → repo-count (present only when the scoped set crosses more than one profile).

Report sections (customer / internal):

Summary (1 run): stat cards (including Quality Score 0–10 — see below), severity/tool/category distribution charts, top-15 repos table with severity bars, top-20 rules table, code-by-language breakdown, filterable all-repos table. Internal also renders the methodology footer and rule-sample messages.
Compare (2 runs): delta cards (before/after/Δ/%), including quality score delta (higher is better — green when score improves, red when it degrades), grouped bar charts by severity/tool/language, per-repo delta table, new rules firing, rules resolved, methodology-change warning if profile or toolchain hashes differ.
Trend (N runs): headline first→last delta cards (including quality score change), total findings over time (line), total LOC over time (line), findings by severity over time (stacked area), findings by tool over time (multi-line), language composition over time (stacked area), quality score over time (line), per-repo sparkline grid, full runs table.

Quality Score. Every report shows a 0–10 code quality index computed from severity-weighted finding density per KLOC:

quality_score = max(0, 10 − weighted_sum / max(KLOC, 5))

Weights: Critical × 10, High × 5, Medium × 2, Low × 1, Info × 0. The KLOC denominator is floored at 5 to avoid penalising small repos disproportionately. A codebase with zero findings scores 10. Color tiers in reports: ≥ 8 = green (good), 5–7.9 = amber (ok), < 5 = red (poor). The XLSX dev report Summary sheet also includes the quality score.

Report sections (dev):

Header with run name, date, customer, product, and active profile.
Severity cards (critical/high/medium/low/info counts across the filtered set).
Profile-distribution table — shown only when the scoped repos cross profile boundaries.
Filter strip: free-text search, per-severity checkboxes, tool / repo / group / category dropdowns.
Findings table: sev · repo · group · tool · rule · category · file · line · message · CWE. Clicking a row expands an inline syntax-highlighted snippet (plaintext fallback when no snippet was captured). The “file” column is the path relative to the repo root (e.g. config/loader.go), which is how the scanners’ absolute paths are normalized before being persisted.
Methodology footer (run_id, profile, ruleset hash, toolchain hash, src_root).

`argus enrich`

Fetches CVE and CVSS scoring data from the NIST National Vulnerability Database (NVD) for findings in a completed run, and caches results in argus.db alongside the scan data.

argus enrich [flags]

Flag	Default	Description
`--db`	`argus.db`	Path to the argus DuckDB database
`--run`	`latest`	Run ID, run name, or `latest`
`--api-key`	—	NVD API key (register free at nvd.nist.gov)
`--ttl`	`24h`	Skip NVD for CVEs already enriched within this duration

argus enrich is a one-shot post-scan step, not a daemon. Run it after argus run completes:

argus run --src ~/workspace --config config.yaml --name "Q1 Scan"
argus enrich --run "Q1 Scan"
argus enrich --run "Q1 Scan" --api-key $NVD_API_KEY    # higher rate limit

NVD rate limits: without an API key, NVD allows 5 requests per 30 seconds. With --api-key, the limit rises to 50 per 30 seconds. For large scan sets with hundreds of CVEs, the API key is strongly recommended. Register for free at nvd.nist.gov/developers/request-an-api-key.

Caching. Enrichment results are stored in the cwes, cves, and vulnerabilities tables in argus.db. The --ttl flag controls how long a cached entry stays fresh — CVEs enriched more recently than the TTL are skipped. Runs that share CVEs benefit from the cache: NVD is called once per CVE, not once per run.

`argus runs`

Inspect and manage the runs stored in the database.

argus runs list   [--db argus.db] [--last 20]
argus runs delete --run <spec> [--db argus.db] [--yes] [--dry-run]

`argus runs list`

Prints a table of scan runs, newest first.

Flag	Default	Description
`--db`	`argus.db`	DuckDB path
`--last`	`20`	Maximum rows to show (`0` = all)

`argus runs delete`

Removes a run and every row associated with it — run_repos, code_stats, files, findings, and resolved_profile. The NVD enrichment cache (cwes, cves, vulnerabilities) is not affected — those tables are cross-run and deleting a run does not invalidate CVE data.

Flag	Default	Description
`--db`	`argus.db`	DuckDB path
`--run`	(required)	Run ID, run name, or `latest`
`--yes`	`false`	Skip confirmation prompt
`--dry-run`	`false`	Show what would be deleted without making changes

By default the command prints a summary of what will be removed and asks you to type the run name to confirm. Use --yes to bypass the prompt in scripts.

argus runs list
argus runs delete --run latest                    # prompts for confirmation
argus runs delete --run "Q1 Scan" --yes           # no prompt
argus runs delete --run run-1713456789123 --dry-run  # plan only

`argus consolidate`

Processes one or more completed runs to derive cross-run issue lifecycle state. This is a separate post-scan step — argus run writes raw findings, argus consolidate derives issue state from them.

argus consolidate [flags]

Flag	Default	Description
`--db`	`argus.db`	Path to the argus DuckDB database
`--run`	—	Run ID, run name, or `latest` (mutually exclusive with `--all`)
`--all`	`false`	Process all completed-but-unconsolidated runs in chronological order
`--force`	`false`	Re-process already-consolidated runs (idempotent re-run)
`--similarity`	`90`	Minimum git rename similarity score (0–100)

Exactly one of --run or --all is required.

Issue lifecycle states:

Status	Meaning
`open`	Seen in the latest consolidated run for its repo
`resolved`	Was open/regressed, absent from the most recent scan of its repo
`regressed`	Was resolved, then reappeared in a later run

Typical workflow:

# After each new scan
argus run --src ~/workspace --config config.yaml --name "Apr 2026"
argus consolidate --run latest

# Bootstrap from historical data (run once)
argus consolidate --all

Issue identity:

Issues are identified by a 16-hex-character SHA derived from the file and rule:

file_id   = sha256(customer_id + NUL + product_id + NUL + repo_alias + NUL + canonical_path)[:16]
issue_id  = sha256(file_id + NUL + rule_id)[:16]

This means the same bug in the same file tracked by the same rule always has the same issue_id — regardless of which run detected it. Moving a file breaks the file_id (and therefore the issue_id) unless git rename detection is available; in that case argus consolidate re-keys the issue automatically.

--all and historical backfill. When bootstrapping from existing scan history, run argus consolidate --all once. It processes runs oldest-first so lifecycle state builds correctly — a finding that was open in January, resolved in February, and reappeared in March will correctly show regressed after processing all three runs in order.

`argus issues`

Query cross-run issue lifecycle state. Run argus consolidate first to populate the issues table.

argus issues list  [flags]
argus issues stats [flags]

`argus issues list`

Prints a filterable table of tracked issues.

Flag	Default	Description
`--db`	`argus.db`	DuckDB path
`--status`	`open`	Filter by status: `open`, `resolved`, `regressed`, `all`
`--repo`	(all)	Filter by repo alias (substring match)
`--severity`	(all)	Filter by severity: `critical`, `high`, `medium`, `low`
`--tool`	(all)	Filter by tool name (substring match)
`--last`	`100`	Maximum rows to show (`0` = all)
`--sort`	`severity`	Sort order: `severity`, `first_seen`, `last_seen`, `runs`

argus issues list                                    # open issues, sorted by severity
argus issues list --status all                       # all issues regardless of status
argus issues list --status regressed --severity high # high-severity regressions
argus issues list --repo lib-chassis --tool gosec    # gosec findings in one repo
argus issues list --sort runs --last 20              # most persistent issues first

`argus issues stats`

Prints overall counts by status and severity, plus a per-run trend table.

Flag	Default	Description
`--db`	`argus.db`	DuckDB path
`--repo`	(all)	Restrict to a specific repo alias (exact match)
`--last`	`20`	Number of runs to include in the per-run trend (`0` = all)

argus issues stats                        # overall summary
argus issues stats --repo payments-api    # restrict to one repo

`argus version`

Prints version, commit, build number, build timestamp, and platform.