# Quick Start

Want to look before installing? [Try the demo in your browser](https://koda-ai-studio.github.io/agent-bom/demo/): a
read-only copy of the UI on labelled sample data.

## Install

```bash
pip install agent-bom
```

## Scan a project and save the evidence

```bash
agent-bom scan . -f html -o agent-bom-report.html
```

Open `agent-bom-report.html` to inspect inventory, findings, coverage and fix
guidance. This scans only the selected project: manifests, lockfiles, MCP
configuration, secrets and personal data, skills and IaC. It does not read agent
configuration elsewhere on the machine. Adding `--no-discover` would also turn
off the project's secret, personal-data, skill, dataset and training-pipeline scanning. No MCP configuration? Package findings remain useful; agent/tool
relationships need discovered configuration or an explicit inventory.
A non-zero exit can be a security verdict or incomplete assessment; inspect the
saved report and its coverage warnings. After a reviewed fix, rerun the command
against the same project and compare the reports.

## Scan a project plus local agent context

```bash
agent-bom scan -p .
```

Use this when you want one scan to cover both:
- project manifests and lockfiles in the current repo
- local MCP / agent context on your machine

## Open your project evidence in the dashboard

```bash
pip install 'agent-bom[ui]'
agent-bom quickstart --project /path/to/repository --dry-run
agent-bom quickstart --project /path/to/repository --run
```

This scans only the selected project's manifests, lockfiles and MCP
configuration, retains a private JSON report, and reads back the exact scan
and graph before printing Findings and Investigation links. Start the printed
server command before opening them. Each run has a separate evidence directory;
the command does not alter project files or apply fixes.

A partial scan can also activate its retained evidence after both database
readbacks succeed. Its receipt records `scan_outcome: partial`, the command
still exits **1**, and the report retains `scan_run` and `coverage_warnings`.
Failed scans or unverifiable graphs do not receive an activation receipt.

Overview separates test/fixture, example, documentation and unclassified path
contexts. Select a context to review matching Findings; headline posture still
includes all contexts. Path names alone do not prove deployment or justify
suppressing a finding. Original severities and compliance evidence remain.

Dashboard reads omit bulk AST relationship lists. The authenticated
`GET /v1/scan/{job_id}/dashboard` response links these lists under
`result.analysis_sections`; follow each link with `offset` and `limit` (maximum
1,000) to retrieve redacted pages. Full report reads and artifact downloads
retain the relationship evidence.

Add `--offline` to skip package-CVE lookup; zero CVEs then is not a clean
security verdict. Non-default tenants require a matching authenticated
principal. See the [first-run guide](https://github.com/koda-ai-studio/agent-bom/blob/main/docs/FIRST_RUN.md#activate-your-own-project-in-the-dashboard)
for retained receipts, database configuration and failure behavior.

## Scan instruction and skill files

```bash
agent-bom skills scan .
agent-bom skills verify .
```

This covers `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, and supported `skills/*`
instruction surfaces.

## Check a specific package before installing

```bash
agent-bom check langchain@0.2.17 --ecosystem pypi
agent-bom check express@4.18.2 --ecosystem npm
agent-bom check tensorflow@2.17.0 --ecosystem pypi
```

## Export machine-readable output

```bash
agent-bom scan -f json -o report.json
agent-bom scan -f sarif -o findings.sarif
agent-bom scan -f cyclonedx -o bom.json
```

On an empty or offline dashboard, use **Preview a saved report** to choose
`report.json`. The browser checks every agent and exposure entry, validates
finding totals, and rejects files larger than 10 MB before previewing them.
Rejected reports leave the current view intact. This preview does not upload
evidence or populate the control-plane graph; use **Return to live overview**
to leave it, or ingest the report's evidence through a supported control-plane
workflow.

## Ingest external scanner or SARIF evidence

When an SCA, SBOM, or SAST tool already
produced a report, run full local scan depth without a control plane:

```bash
agent-bom scan --external-scan trivy.json -f json -o report.json
agent-bom scan --external-scan findings.sarif -f json -o report.json  # tool-agnostic import; no producer execution
```

For bulk push into a running control plane instead, use
`agent-bom findings push <file>`. See
[docs/INGEST_PATHS.md](https://github.com/koda-ai-studio/agent-bom/blob/main/docs/INGEST_PATHS.md)
for the VM/registry matrix and push vs `--external-scan` tradeoff.

## LLM FinOps (cost forecast)

Project LLM burn rate from OpenTelemetry GenAI spans (read-only, no secret values):

```bash
agent-bom cost forecast
```

Price model and OTel ingest path: [docs/COST_MODEL.md](https://github.com/koda-ai-studio/agent-bom/blob/main/docs/COST_MODEL.md).

## Run compliance mapping

```bash
agent-bom scan . --compliance
agent-bom scan . --compliance --compliance-export owasp-llm
agent-bom scan . --compliance --compliance-export eu-ai-act
```

`--compliance` adds all mapped framework tags to findings. Use
`--compliance-export <framework>` when you also need one framework-specific
evidence bundle.

## Scan a container image

```bash
agent-bom image python:3.12-slim
```

## Scan infrastructure as code

```bash
agent-bom iac Dockerfile k8s/ infra/main.tf
```

`iac` accepts one or more paths in a single run, so the example above scans:
- a Dockerfile
- a Kubernetes directory
- a Terraform file

## Inspect discovery paths

```bash
agent-bom where
agent-bom mcp inventory
```

`agent-bom mcp where` still works when you want the grouped MCP subcommand form.

## Output formats

```bash
agent-bom scan -f console  # terminal output (default)
agent-bom scan -f json     # JSON report
agent-bom scan -f html     # HTML dashboard
agent-bom scan -f sarif    # SARIF for GitHub Code Scanning
agent-bom scan -f csv      # CSV export
agent-bom check requests@2.33.0 -e pypi -f json   # single-package JSON verdict
agent-bom report history -f json                  # saved scan metadata for CI
```

If a GitHub Action produces SARIF but no Code Scanning alert appears, check the
[SARIF upload troubleshooting guide](https://github.com/koda-ai-studio/agent-bom/blob/main/docs/GITHUB_ACTION_SARIF_TROUBLESHOOTING.md)
for token permissions, fork PR behavior, report paths, and category settings.