CLI Reference

airom is a single static binary. Every command below is real and current; every flag listed is the complete set for that command. Cobra also supplies help and completion, which behave as they do in any Cobra tool.

Shape of an airom invocation

airom <command> [args] [flags]

The global flags are persistent — every command accepts them — but only the scan-family commands (scan, fs, repo, image, k8s) use the full set. Elsewhere: detectors list, detectors explain, and rules list resolve the same configuration and so honor --select and --rules; clean honors --cache-dir. rules lint, rules test, and the dev scaffolds ignore configuration entirely and act only on the file or name you give them. -v/-q set log verbosity on every command.

Scan commands

airom scan

Scan a target, auto-detecting the scheme.

airom scan

airom scan <target>

Detection order: an existing local path, then a git URL, then an image reference. Explicit prefixes force the interpretation.

Prefix	Forces
`dir:`	directory tree
`repo:`	git repository
`image:`	container image

Auto-detect vs. explicit

airom scan .
airom scan https://github.com/airomhq/airom
airom scan image:my-app:latest
airom scan dir:./services/inference

Exactly one <target> is required. No command-specific flags.

airom fs

Scan a directory tree.

airom fs

airom fs <path>

Exactly one <path> is required; it must exist. No command-specific flags.

airom repo

Scan a git repository.

airom repo

airom repo <url|path>

A remote URL is shallow-cloned. A local path is scanned as a worktree. Exactly one argument is required. No command-specific flags.

airom image

Scan a container image.

airom image

airom image [ref]
airom image --input <tarball>

string

Scan a saved image tarball (docker save output or an OCI archive). No network.

string

Platform to select from a multi-arch index, e.g. linux/arm64.

A reference and --input are mutually exclusive, and at least one of the two is required.

Live registry and Docker-daemon pulls are not wired yet — they fail with a clear error. Today, scan an image from a tarball (--input) or an OCI layout on disk.

Offline image scan

docker save my-app:latest -o my-app.tar
airom image --input my-app.tar --offline

airom k8s

Scan the images of Kubernetes workloads.

airom k8s

airom k8s [context]
airom k8s --manifests <dir>

string

Offline mode: extract image references from manifest YAML in this directory.

string

Restrict to one namespace.

bool

default:"false"

All namespaces.

bool

default:"false"

Scan the discovered images concurrently. Serial by default.

At most one positional [context] (a kubeconfig context name).

Live-cluster mode is not wired yet — it fails with a clear error. Use --manifests <dir> to extract image refs from YAML offline.

Offline manifest scan

airom k8s --manifests ./deploy/k8s --offline

Inspection commands

airom diff

Compare two native AIBOM documents and report the semantic delta: components added, removed, and changed, keyed by the stable component ID. A version bump reads as a field change on one component, never as a remove+add pair; evidence churn is not compared, so two scans of unchanged code diff as empty.

airom diff

airom diff old.json new.json
airom diff base.json head.json --format markdown
airom diff base.json head.json --fail-on "hosted-llm|local-model-file"
airom diff base.json head.json --exit-code 1

Exactly two native AIBOM JSON files are required (airom scan <target> -o json=<file>); other formats are refused explicitly. --format selects one of table (default), markdown (ready to post as a PR comment), or json. The gate flags work like scan’s, evaluated over the added and changed components only — removals never trip the gate, and compliance: terms are rejected. Test-scoped components are excluded unless --include-tests is set. Added and removed components carry a Risk, Vulnerabilities, or Lifecycle column when that section surfaces one, so a PR introducing a retired model or a checkpoint that executes code on load says so in the row. Both documents must come from the same tooling. airom diff compares the two tool blocks — binary version, ruleset version and hash, lifecycle catalog — and reports any mismatch as ⚠ Not comparable in every format. A rule added between the two scans makes components appear that the PR never wrote; a rule removed makes them vanish. With --fail-on active a mismatch is a fatal error (exit 2) rather than a pass or a failure, the same refusal an unevaluable eol/cve gate gives: skipping the gate would be a false green and running it a false red. Scan base and head in one CI run and this never fires.

airom detectors list

List every detector with its selection status. Honors --select and --rules, so the listing reflects the configuration you would actually scan with.

airom detectors list

airom detectors list
airom detectors list --select "rules,+modelfile/gguf"

Columns: ID, VERSION, PHASE, SELECTED, SELECTS. No arguments, no command-specific flags.

airom detectors explain

Print one detector’s full selector, its need, and its rule count.

airom detectors explain

airom detectors explain <id>

Exactly one <id> is required. Output fields: id, version, phase, selects, need, selected. An unknown id is a configuration error.

airom rules list

Show the effective ruleset — embedded packs plus --rules overlays — with each rule’s layer.

airom rules list

airom rules list
airom rules list --rules ./my-pack.yaml

Columns: RULE ID, KIND, CONFIDENCE, LAYER, followed by a rule count. No arguments, no command-specific flags.

airom rules lint

Validate a rule pack — or a model lifecycle catalog — against its full contract. The signed bundle carries both, so one command checks either; the file’s shape selects the validator.

airom rules lint

airom rules lint <file>
airom rules lint eol/openai.yaml

Exactly one <file>. For a rule pack: reports failures and rules missing a positive or negative fixture. For a lifecycle catalog: enforces the honesty contract (a source URL and verification date on every file, parseable states and dates, no transposed or self-referential records). A failing file exits non-zero.

airom rules test

Run a rule pack against its fixtures. No Go toolchain required.

airom rules test

airom rules test <file>

Exactly one <file>. Prints <file>: OK (n expectation(s) checked) on success; failures exit non-zero. Handed a model lifecycle catalog it says so and exits 0 — a catalog has no fixtures to run, and it is rules lint that validates one. That keeps a publishing pipeline free to run both commands over every YAML in the bundle without special-casing which file is which.

airom rules update

Fetch, verify, and cache a signed rule bundle from the airom-rules release channel. A bundle may also carry the model lifecycle catalog, so this is what refreshes retirement dates without a binary upgrade. This is the only rules subcommand that touches the network — scans never do. See Rule updates for the full model.

airom rules update

airom rules update              # the latest release
airom rules update v1.2.0       # a pinned version

Flag	Type	Default	Description
`--rules-source`	string	the airom-rules release channel	Base URL override (mirror or testing).
`--insecure-skip-signature`	bool	`false`	Skip ed25519 verification (not recommended); the tarball checksum is still enforced.

The bundle is verified against the public key embedded in airom (signature, then tarball SHA-256) and cached under <cache-dir>/rules/<version>; any failure is fatal and leaves the previous bundle in place. --offline refuses to fetch. airom clean removes it.

Contributor commands

airom dev new-rulepack

Scaffold a rule pack plus fixtures.

airom dev new-rulepack

airom dev new-rulepack <name>

string

default:"models"

Rule category directory. One of: models, embeddings, frameworks, vectordb, infra, params, prompts, datasets.

<name> must match [a-z0-9-]+. Writes rules/<category>/<name>.yaml and a fixture under rules/<category>/testdata/<name>/. Refuses to overwrite an existing pack.

airom dev new-detector

Scaffold a Go code detector plus a contract test.

airom dev new-detector

airom dev new-detector <name>

<name> must match [a-z0-9-]+. Writes internal/detectors/<pkg>/ containing <pkg>.go, <pkg>_test.go, and a testdata/ directory, where <pkg> is <name> with the dashes removed (new-detector safetensors-header scaffolds internal/detectors/safetensorsheader/) — a Go package name cannot contain a dash. Refuses to overwrite an existing directory. No command-specific flags. It then prints the two follow-up steps: go test ./internal/detectors/<pkg>/ -update to write goldens, and go generate ./internal/detectors/all to register the detector.

Utility commands

airom clean

Remove the scan cache.

airom clean

airom clean
airom clean --cache-dir /var/cache/airom

Resolves the cache directory through the normal configuration layering and removes it. No arguments, no command-specific flags. The removal is guarded: airom clean refuses any directory whose basename is not airom or airom-cache, and refuses your home directory or a filesystem root.

airom version

Print the version, commit, and build date — the same ToolInfo embedded in every AIBOM.

airom version

airom version

No arguments, no command-specific flags.

Global flags

This table is the complete global flag set, on top of the two Cobra built-ins every command carries: -h/--help, and --version on the root.

Flag	Type	Default	Meaning
`--cache-dir`	string	`<user cache dir>/airom`	Scan cache location (also where fetched rule bundles live).
`--cdx-version`	string	`1.6`	CycloneDX spec version: `1.6` or `1.7`.
`--no-cached-rules`	bool	`false`	Ignore any fetched rule bundle; scan with the built-in packs. See Rule updates.
`--compliance`	stringArray	—	Map the AIBOM onto a governance framework (`nist-ai-rmf`, `owasp-agentic`). Repeatable.
`--no-eol`	bool	`false`	Disable the model lifecycle (EOL) overlay, which is on by default. It matches inventoried AI models against a curated catalog of provider retirement announcements. The catalog is local — from a fetched bundle when one carries it, else embedded — so unlike `--no-cve` it needs no network and survives `--offline`. See Model lifecycle.
`--include-tests`	bool	`false`	Count AI found only in test scaffolding (`testdata/`, `_test.go`, `tests/`, `spec/`, `test_.py`, `*.spec.ts`, …), matched against scan-root-relative paths. Off by default — a rule-pack fixture is not part of what your software uses. Test-scoped components stay in the native JSON (`testOnly: true`) and CycloneDX (`scope: "excluded"`); this flag decides whether the table, SARIF, and `--fail-on` count them. See Test scope.
`--no-cve`	bool	`false`	Disable the OSV.dev CVE overlay, which is on by default. The overlay matches AI dependencies against OSV.dev for known CVEs; it queries the network and is not deterministic over time, so `--no-cve` (or `--offline`) gives a byte-stable offline BOM. See CVE overlay.
`--exit-code`	int	`1` when a policy is active	Exit status when `--fail-on` matches. `0` reports matches without failing.
`--fail-on`	string	—	CI policy expression, e.g. `"hosted-llm&confidence>=0.9"`.
`--format`	string	—	Single-format alias for `-o`. Mutually exclusive with `-o`.
`--ignore`	stringArray	—	Additional ignore glob. Repeatable. Applied on top of `.gitignore`/`.airomignore`.
`--io-budget`	string	`256m`	Byte-weighted I/O semaphore budget (`k`/`m`/`g` suffixes).
`--max-file-size`	string	`1m`	Full-content read cap for text detectors (`k`/`m`/`g` suffixes).
`--min-confidence`	float	`0`	Presentation-layer confidence filter, `0`–`1`.
`--no-cache`	bool	`false`	Disable cache reads and writes for this run.
`--offline`	bool	`false`	Assert no network access for the entire run.
`-o, --output`	stringArray	`table` to stdout	Output as `fmt[=path]`. Repeatable. Formats: `cyclonedx`, `json`, `sarif`, `table`, `yaml`.
`--parallel`	int	`GOMAXPROCS`	Worker count.
`--pprof`	string	—	Serve `net/http/pprof`. Bare flag = `localhost:6060`.
`-q, --quiet`	bool	`false`	Errors only.
`--rules`	stringArray	—	Overlay rule pack file. Repeatable. Merged by rule ID.
`--sarif-strict-kinds`	bool	`false`	Emit spec-pure `kind:"informational"` instead of `level:"note"`.
`--select`	string	—	Detector selection expression, e.g. `"rules,+modelfile/gguf,-dataset/file"`.
`--stats`	bool	`false`	Emit the full `ScanStats` block in the output.
`--wide`	bool	`false`	Table output only: list every `file:line` occurrence under each component. The default table shows just the primary `LOCATION` and an occurrence count.
`--no-progress`	bool	`false`	Disable the scan progress spinner. Auto-off when stderr is not a terminal, and under `-q`. Progress is stderr-only and never affects the emitted AIBOM.
`--trace`	string	—	Write a Go execution trace to file.
`-v, --verbose`	count	`0`	Increase log verbosity. Repeatable; `-vv` adds source locations.

Flag notes

--pprof: a custom address must be attached with '='

--pprof is a bare-flag-with-value flag. Given alone it binds localhost:6060. A custom address must be attached with =:

--pprof forms

airom fs .  --pprof                   # localhost:6060
airom fs .  --pprof=0.0.0.0:7070      # custom address — note the '='

The space-separated spelling --pprof 0.0.0.0:7070 is rejected up front with a precise error. It has to be: the address would otherwise be parsed as a positional argument (on airom k8s it would silently become the kubeconfig context, while pprof quietly bound the default port).

-v is logging-only

-v/--verbose changes log verbosity and nothing else. Default level is info; -v enables debug; -vv adds source locations. It does not change the table output, add columns, or reveal more components. To see more components, lower --min-confidence; to see more detail in the document, use --stats or a structured format via -o.-q and -v are mutually exclusive when both are passed on the command line.

--format vs. -o/--output

--format is a convenience alias for a single -o. Passing both explicitly on the command line is an error. Use repeated -o for multi-output:

Multi-output

airom fs . -o table -o cyclonedx=aibom.cdx.json -o sarif=airom.sarif

Exit codes

Code	Meaning
`0`	Scan completed successfully. Findings are not failures.
`<n>`	The `--exit-code` value, when `--fail-on` matches. Defaults to `1` when a policy is active.
`2`	Fatal error: bad configuration or flags, source acquisition failure.

--exit-code alone, with no --fail-on, means “fail on any component”. --exit-code 0 with an active --fail-on reports matches without failing the build — useful for a soft rollout of a new gate.

The —fail-on grammar

Grammar

expr       = clause *( "|" clause )      ; OR
clause     = term   *( "&" term )        ; AND — all terms must hold for ONE component
term       = ident | risk | cve | eol | compliance | comparison
ident      = a ComponentKind ("hosted-llm")
risk       = "risk" | "risk:<severity>" | "risk:<slug>"        ; see Risk detection
cve        = "cve"  | "cve:<severity>"                          ; threshold; overlay is on by default
eol        = "eol"  | "eol:<state>" | "eol:before:<YYYY-MM-DD>"  ; model lifecycle; on by default
compliance = "compliance:gap" | "compliance:<fw>" | "compliance:<fw>:<control>" ; requires --compliance
comparison = "confidence" OP number      ; OP: >= <= > < =

& binds tighter than |. Every term in a clause must hold for the same component — a clause is a per-component predicate, not a whole-document one. An unknown term is a usage error at parse time, never a silently-passing gate.

Policy examples

airom fs . --fail-on "hosted-llm"
airom fs . --fail-on "risk:high"
airom fs . --fail-on "cve:high"             # high AND critical (overlay on by default)
airom fs . --fail-on "eol:retired"          # a model that already stopped answering
airom fs . --fail-on "eol:before:2027-01-01" # anything dying before the next release train
airom fs . --fail-on "hosted-llm&confidence>=0.9"
airom fs . --fail-on "local-model-file|hosted-llm&confidence>=0.8"

Any of the 13 component kinds may be used as an ident: hosted-llm, local-model-file, embedding-model, framework, library, vector-db, prompt, dataset, ai-config, infra, service, rag-pipeline, application. Beyond kinds: the risk selectors (risk, risk:<severity>, risk:<slug>; pickle-risk is a deprecated alias for risk:pickle-import), the CVE selectors (cve, cve:<severity> — a threshold; the overlay is on by default), the model-lifecycle selectors (eol, eol:retired, eol:deprecated — a threshold — and eol:before:<YYYY-MM-DD>, which fails when anything dies before a date you name), and the compliance selectors (compliance:gap, compliance:<framework>, compliance:<framework>:<control>; requires --compliance, cannot be &-combined).

Table output

The default output is a table on stdout.

airom fs .

AI Bill of Materials — /tmp/my-ai-app

┌─ Scan Summary ───────────────┐
│ Target        /tmp/my-ai-app │
│ Components    6              │
│ Relationships 1              │
│ Files         2 scanned      │
│                              │
│ By Type                      │
│   ai-config          2       │
│   framework          1       │
│   hosted-llm         1       │
│   library            1       │
│   vector-db          1       │
└──────────────────────────────┘

┌────────────┬─────────────┬─────────┬───────────┬───────┬────────────────────┬──────────┐
│ KIND       │ NAME        │ VERSION │ PROVIDER  │ CONF  │ LOCATION           │ EVIDENCE │
├────────────┼─────────────┼─────────┼───────────┼───────┼────────────────────┼──────────┤
│ ai-config  │ max_tokens  │ -       │ -         │ 0.5   │ src/rag.py:10      │ 1 occ    │
│ ai-config  │ temperature │ -       │ -         │ 0.5   │ src/rag.py:9       │ 1 occ    │
│ framework  │ langchain   │ 0.2.16  │ langchain │ 0.95  │ requirements.txt:1 │ 1 occ    │
│ hosted-llm │ gpt-4.1     │ -       │ openai    │ 0.85  │ src/rag.py:8       │ 1 occ    │
│ library    │ openai      │ 1.51.0  │ openai    │ 0.985 │ requirements.txt:2 │ 2 occ    │
│ vector-db  │ chroma      │ 0.5.5   │ chroma    │ 0.985 │ requirements.txt:3 │ 2 occ    │

A boxed Scan Summary panel (target, counts, a By-Type breakdown, and a Vulnerabilities-by-severity breakdown when the CVE overlay ran) precedes the table. Columns are KIND, NAME, VERSION, PROVIDER, CONF, LOCATION, EVIDENCE, plus a VULN column (and a per-CVE detail table below) when a scan surfaces CVEs. LOCATION is the primary sighting (path:line) and EVIDENCE renders as n occ — the number of occurrences backing the component. --wide lists every one.

Configuration reference

Every flag here can also come from AIROM_* env vars or .airom.yaml.

Get started

Concepts

Scanning

Output

CI/CD

Rules

Reference

CLI Reference

Scan commands

airom scan

airom fs

airom repo

airom image

airom k8s

Inspection commands

airom diff

airom detectors list

airom detectors explain

airom rules list

airom rules lint

airom rules test

airom rules update

Contributor commands

airom dev new-rulepack

airom dev new-detector

Utility commands

airom clean

airom version

Global flags

Flag notes

Exit codes

The —fail-on grammar

Table output

Configuration reference

​Scan commands

​airom scan

​airom fs

​airom repo

​airom image

​airom k8s

​Inspection commands

​airom diff

​airom detectors list

​airom detectors explain

​airom rules list

​airom rules lint

​airom rules test

​airom rules update

​Contributor commands

​airom dev new-rulepack

​airom dev new-detector

​Utility commands

​airom clean

​airom version

​Global flags

​Flag notes

​Exit codes

​The —fail-on grammar

​Table output

Configuration reference

Scan commands

airom scan

airom fs

airom repo

airom image

airom k8s

Inspection commands

airom diff

airom detectors list

airom detectors explain

airom rules list

airom rules lint

airom rules test

airom rules update

Contributor commands

airom dev new-rulepack

airom dev new-detector

Utility commands

airom clean

airom version

Global flags

Flag notes

Exit codes

The —fail-on grammar

Table output