up

docs/modules/cli/guides/graph-and-vuln.md

@@ -0,0 +1,82 @@
+# 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).