# CLI Guide · Graph & Vulnerability

Status: Draft (2025-11-26) — reflects current Graph API surface; Vuln API pending (see docs/api/vuln.md).

## Prereqs
- `stellaops-cli` built from current repo.
- Auth token with scopes: `graph:read`, `graph:query`, `graph:export` (and `vuln:read` when Vuln API lands).
- Tenant header is required for all calls (`--tenant`).

## Commands

### Search graph
```bash
stella graph search \
  --tenant acme \
  --kinds component \
  --query "pkg:npm/" \
  --limit 20 \
  --format ndjson
```
Outputs NDJSON tiles (`node`, optional `cursor`).

### Query graph with budgets
```bash
stella graph query \
  --tenant acme \
  --kinds component \
  --query widget \
  --include-edges \
  --budget-tiles 200 \
  --budget-nodes 150 \
  --budget-edges 100 \
  --format ndjson
```
Returns nodes/edges/stats/cursor with cost metadata. If edge budget is exceeded, an `error` tile with `GRAPH_BUDGET_EXCEEDED` is returned.

### Paths
```bash
stella graph paths \
  --tenant acme \
  --source gn:acme:component:one \
  --target gn:acme:component:two \
  --max-depth 4 \
  --include-edges \
  --format ndjson
```

### Diff snapshots
```bash
stella graph diff \
  --tenant acme \
  --snapshot-a snapA \
  --snapshot-b snapB \
  --include-edges \
  --format ndjson
```

### Export graph
```bash
stella graph export \
  --tenant acme \
  --format ndjson \
  --include-edges \
  --kinds component \
  --query "pkg:npm/" \
  --out graph-export.ndjson
```
Manifest is returned with jobId, sha256, size, and download URL; CLI downloads to `--out`.

### Vuln lookup (placeholder)
Pending Vuln Explorer API; for now use graph search/query to inspect impacted components. See `docs/api/vuln.md`.

## Exit codes
- `0` success
- `2` validation error (missing kinds/tenant/scopes)
- `3` budget exceeded (error tile received)
- `4` network/auth failure

## Tips
- Add `--format table` (when available) for quick summaries; default is NDJSON.
- Use `--cursor` from a previous call to page results.
- To sample overlays, pass `--include-overlays` (budget permitting).