docs/api/cli.md

# API Reference — `hf-scanner` CLI

The `hf-scanner` CLI is built with [Typer](https://typer.tiangolo.com/). Install it as a package entrypoint:

```bash
pip install -e .
hf-scanner --help
```

Or run directly from the source tree:

```bash
python cli.py --help
```

---

## Global options

```
hf-scanner [OPTIONS] COMMAND [ARGS]...
```

| Option | Description |
|--------|-------------|
| `--help` | Show help and exit |
| `--install-completion` | Install shell completion |
| `--show-completion` | Print completion script |

---

## `hf-scanner version`

```bash
hf-scanner version
```

Print the scanner version string.

**Output:**
```
hf-scanner 4.0.0
```

---

## `hf-scanner list-rules`

```bash
hf-scanner list-rules
```

List all bundled Semgrep rule packs with their category and file path.

**Output:**
```
Pack                            Category        Path
----------------------------------------------------------------------
Semgrep:Core                    security        /path/to/core.yaml
Semgrep:Web                     security        /path/to/web.yaml
...
```

---

## `hf-scanner self-test`

```bash
hf-scanner self-test
```

Check that all external tools are available on PATH. Auto-downloads gitleaks and hadolint binaries if missing.

**Output:**
```
Tool                Status    Description
------------------------------------------------------------
semgrep             ✓  ok     Static analysis (Python, JS, …)
bandit              ✓  ok     Python security linter
detect-secrets      ✓  ok     Secret detection
pip-audit           ✓  ok     Dependency CVE scanner
ruff                ✓  ok     Fast Python linter (perf rules)
gitleaks            ✗  MISSING  Git history secret scanner
hadolint            ✗  MISSING  Dockerfile linter
agent-audit         ✗  MISSING  OWASP Agentic Top 10 scanner

[bootstrap] gitleaks=ok,  hadolint=ok
```

**Exit codes:** `0` = all tools available, `2` = some tools missing.

---

## `hf-scanner scan`

```bash
hf-scanner scan TARGET [OPTIONS]
```

Scan a repository or local directory for security and performance issues.

### Arguments

| Argument | Description |
|----------|-------------|
| `TARGET` | HTTPS URL (HF Space or git repo) or absolute/relative local path |

### Options

#### Output

| Option | Default | Description |
|--------|---------|-------------|
| `--format`, `-f` | `both` | Output format: `html` \| `sarif` \| `json` \| `both` |
| `--out`, `-o` | temp dir | Output directory or file stem (without extension) |
| `--quiet` | — | Suppress all output except findings count |
| `--verbose` | — | Show per-finding details on stdout |

**Output paths when `--out results/scan` is used:**

| Format | Path |
|--------|------|
| `html` | `results/scan.html` |
| `sarif` | `results/scan.sarif` |
| `json` | `results/scan.json` |
| `both` | `results/scan.html` + `results/scan.sarif` |

#### Scan scope

| Option | Default | Description |
|--------|---------|-------------|
| `--security / --no-security` | `True` | Enable/disable security scanners |
| `--llm / --no-llm` | `True` | Enable/disable LLM/agent scanners |
| `--performance / --no-performance` | `True` | Enable/disable performance scanners |
| `--deep-history` | `False` | Full git clone + gitleaks history scan |

#### Suppression

| Option | Default | Description |
|--------|---------|-------------|
| `--baseline PATH` | — | JSON baseline file; suppress known findings |
| `--create-baseline PATH` | — | Save current fingerprints to JSON baseline |
| `--ignore-file PATH` | — | `.hfscanignore`-style suppression file |

#### Threshold and exit

| Option | Default | Description |
|--------|---------|-------------|
| `--severity-threshold` | `WARNING` | Minimum severity for non-zero exit (`ERROR` \| `WARNING` \| `INFO`) |

#### Authentication

| Option | Default | Description |
|--------|---------|-------------|
| `--hf-token` | `$HF_TOKEN` env | Hugging Face Bearer token for private repos |

### Exit codes

| Code | Meaning |
|------|---------|
| `0` | Clean — no findings at or above `--severity-threshold` |
| `1` | Findings found at or above threshold |
| `2` | Runtime error (clone failed, file write error, …) |
| `3` | Usage error (invalid argument combination) |

### Examples

```bash
# Basic scan, both HTML + SARIF output
hf-scanner scan ./my-project

# HF Space, SARIF only, fail only on ERROR
hf-scanner scan https://huggingface.co/spaces/org/app \
  --format sarif --out ./ci/results/scan \
  --severity-threshold ERROR

# Security-only, no LLM rules, output to specific dir
hf-scanner scan . --no-llm --no-performance \
  --format html --out reports/security-only

# Create a baseline to suppress existing issues
hf-scanner scan . --create-baseline .scan-baseline.json

# Subsequent run — only new findings cause failure
hf-scanner scan . --baseline .scan-baseline.json

# Full history scan for committed secrets
hf-scanner scan . --deep-history --no-performance --no-llm

# Suppress known-safe paths via ignore file
hf-scanner scan . --ignore-file .hfscanignore

# JSON output to stdout for custom processing
hf-scanner scan . --format json | jq '.[] | select(.severity == "ERROR")'
```

---

## Programmatic use from Python

The CLI command functions are importable, but for programmatic scanning prefer `core.scanner.scan_repo()` directly:

```python
from core.scanner import scan_repo
from report import generate_html_report, generate_sarif
import json
from pathlib import Path

findings, log = scan_repo(
    "./my-project",
    run_llm=False,
    progress_cb=lambda f, d: print(f"{f:.0%} {d}"),
)

print(log[0])   # "OK (42 unique findings)"

Path("report.html").write_text(
    generate_html_report(findings, {"title": "My Scan"}), encoding="utf-8"
)
Path("report.sarif").write_text(
    json.dumps(generate_sarif(findings, {}), indent=2), encoding="utf-8"
)
```