CLI Reference
The ai-bom CLI is the primary interface for scanning projects. It is built with Typer and supports rich terminal output.
Commands
ai-bom scan
Scan a directory, file, or git repository for AI/LLM components.
ai-bom scan [TARGET] [OPTIONS]
Arguments:
| Argument | Default | Description |
|---|---|---|
TARGET | . | Path to scan (file, directory, or git URL) |
Options:
| Flag | Short | Default | Description |
|---|---|---|---|
--format | -f | table | Output format (see Output Formats) |
--output | -o | None | Write output to file |
--deep | false | Enable AST-based deep Python analysis | |
--severity | -s | None | Minimum severity filter: critical, high, medium, low |
--no-color | false | Disable colored output | |
--quiet | -q | false | Suppress banner and progress (for CI) |
--verbose | -v | false | Show scanner details, file counts, and timing |
--debug | false | Enable debug logging with full stack traces | |
--fail-on | None | Exit code 1 if severity threshold met | |
--policy | None | Path to YAML policy file for CI/CD enforcement | |
--config | None | Path to .ai-bom.yml config file | |
--save-dashboard | false | Save scan results to dashboard database | |
--workers | 0 | Number of parallel scanner workers (0 = sequential) | |
--cache / --no-cache | false | Enable incremental scanning cache | |
--max-file-size | 10 | Max file size in MB | |
--n8n-url | None | n8n instance URL for live scanning | |
--n8n-api-key | None | n8n API key (required with --n8n-url) | |
--n8n-local | false | Scan local ~/.n8n/ directory |
Examples:
# Scan current directory
ai-bom scan .
# Scan a git repository
ai-bom scan https://github.com/example/project.git
# Deep scan with AST analysis
ai-bom scan . --deep
# Generate CycloneDX SBOM
ai-bom scan . -f cyclonedx -o ai-bom.cdx.json
# CI mode: fail on critical, SARIF output
ai-bom scan . --fail-on critical -q -f sarif -o results.sarif
# Parallel scanning with 4 workers
ai-bom scan . --workers 4
# Scan n8n instance via API
ai-bom scan . --n8n-url http://localhost:5678 --n8n-api-key YOUR_KEY
# Scan with policy enforcement
ai-bom scan . --policy .ai-bom-policy.yml --quiet
ai-bom scan-cloud
Scan a live cloud provider account for managed AI/ML services.
ai-bom scan-cloud PROVIDER [OPTIONS]
Arguments:
| Argument | Description |
|---|---|
PROVIDER | Cloud provider: aws, gcp, or azure |
Options:
| Flag | Short | Default | Description |
|---|---|---|---|
--format | -f | table | Output format |
--output | -o | None | Write output to file |
--quiet | -q | false | Suppress banner and progress |
Requires the corresponding SDK extra:
pip install ai-bom[aws] # for aws
pip install ai-bom[gcp] # for gcp
pip install ai-bom[azure] # for azure
ai-bom diff
Compare two scan results and show differences.
ai-bom diff SCAN1 SCAN2 [OPTIONS]
Arguments:
| Argument | Description |
|---|---|
SCAN1 | Path to first scan JSON file |
SCAN2 | Path to second scan JSON file |
Options:
| Flag | Short | Default | Description |
|---|---|---|---|
--format | -f | table | Output format: table, json, markdown |
ai-bom dashboard
Launch the web dashboard for viewing scan history.
ai-bom dashboard [OPTIONS]
| Flag | Default | Description |
|---|---|---|
--host | 127.0.0.1 | Host to bind |
--port | 8000 | Port to bind |
Requires the dashboard extra: pip install ai-bom[dashboard]
ai-bom serve
Start the AI-BOM REST API server.
ai-bom serve [OPTIONS]
| Flag | Default | Description |
|---|---|---|
--host | 0.0.0.0 | Host to bind |
--port | 8080 | Port to bind |
Requires the server extra: pip install ai-bom[server]
ai-bom watch
Watch a directory for changes and re-scan automatically.
ai-bom watch [TARGET] [OPTIONS]
| Flag | Short | Default | Description |
|---|---|---|---|
--format | -f | table | Output format |
--verbose | -v | false | Show scanner details |
Requires the watch extra: pip install ai-bom[watch]
ai-bom list-scanners
List all registered scanners and their status.
ai-bom list-scanners
ai-bom demo
Run a demo scan on the bundled example project.
ai-bom demo
ai-bom version
Print the installed AI-BOM version.
ai-bom version
Output formats
| Format | Flag | Use case |
|---|---|---|
| Table | -f table | Rich terminal output with color-coded severity (default) |
| CycloneDX 1.6 | -f cyclonedx | Industry-standard SBOM, compatible with OWASP Dependency-Track |
| JSON | -f json | Alias for CycloneDX |
| SARIF 2.1.0 | -f sarif | GitHub Code Scanning integration |
| SPDX 3.0 | -f spdx3 | SPDX-compatible output with AI extensions |
| HTML | -f html | Shareable dashboard - no server required |
| Markdown | -f markdown | PR comments and documentation |
| CSV | -f csv | Spreadsheet analysis |
| JUnit | -f junit | CI/CD test reporting |
Exit codes
| Code | Meaning |
|---|---|
0 | Scan completed successfully |
1 | Policy violation (from --fail-on or --policy) |
2 | Operational error (bad path, network failure, parse error) |
Policy file
Use a YAML policy file for fine-grained CI/CD enforcement:
# .ai-bom-policy.yml
max_critical: 0
max_high: 5
max_risk_score: 75
block_providers: []
block_flags:
- hardcoded_api_key
- hardcoded_credentials
ai-bom scan . --policy .ai-bom-policy.yml --quiet
Scan levels
AI-BOM's detection depth depends on the access available at scan time:
| Level | Access Required | What It Finds |
|---|---|---|
| L1 - File System | Read-only file access | Source code imports, configs, IaC, n8n JSON, notebooks |
| L2 - Docker | + Docker socket | Running AI containers, GPU allocations |
| L3 - Network | + Env files | API endpoints, hardcoded keys, .env secrets |
| L4 - Cloud IaC | + Terraform/CFN files | 60+ AWS/Azure/GCP AI resource types |
| L5 - Live Cloud | + Cloud credentials | Managed AI services via cloud APIs |
# L1 (default) - works out of the box
ai-bom scan .
# L5 - live cloud scanning
pip install ai-bom[aws]
ai-bom scan-cloud aws
Environment variables
| Variable | Description |
|---|---|
NO_COLOR | Disable colored output (any value) |