git.stella-ops.org/docs/advisory-ai/cli.md

Advisory AI CLI Usage (DOCS-AIAI-31-005)

Updated: 2025-11-24 · Owners: Docs Guild · DevEx/CLI Guild · Sprint 0111

This guide shows how to drive Advisory AI from the StellaOps CLI using the advise run verb, with deterministic fixtures published on 2025-11-19 (CLI-VULN-29-001, CLI-VEX-30-001). It is designed for CI/offline use and mirrors the guardrail/policy contracts captured in docs/advisory-ai/guardrails-and-evidence.md and docs/policy/assistant-parameters.md.

Prerequisites

• CLI binary from Sprint 205 (stella), logged in with scopes advisory-ai:operate + aoc:verify.
• Base URL pointed at Advisory AI gateway: export STELLAOPS_ADVISORYAI_URL=https://advisory-ai.internal (falls back to main backend base address when unset).
• Evidence fixtures available locally (offline friendly):
  • out/console/guardrails/cli-vuln-29-001/sample-vuln-output.ndjson (SHA256 e5aecfba5cee8d412408fb449f12fa4d5bf0a7cb7e5b316b99da3b9019897186).
  • out/console/guardrails/cli-vuln-29-001/sample-sbom-context.json (SHA256 421af53f9eeba6903098d292fbd56f98be62ea6130b5161859889bf11d699d18).
  • out/console/guardrails/cli-vex-30-001/sample-vex-output.ndjson (SHA256 2b11b1e2043c2ec1b0cb832c29577ad1c5cbc3fbd0b379b0ca0dee46c1bc32f6).
• Policy hash pinned: set ADVISORYAI__POLICYVERSION=2025.11.19 (or the bundle hash shipped in the Offline Kit).

Quickstart

stella advise run summary \
  --advisory-key csaf:redhat:RHSA-2025:1001 \
  --artifact-id registry.stella-ops.internal/runtime/api \
  --policy-version "$ADVISORYAI__POLICYVERSION" \
  --profile fips-local \
  --timeout 30 \
  --json

• Use --timeout 0 for cache-only probes in CI; add --force-refresh to bypass cache.
• --profile cloud-openai remains disabled unless tenant consent is recorded in Authority; guardrails reject with exit code 12 when disabled.
• Guardrail fixtures (sample-vuln-output.ndjson, sample-vex-output.ndjson, sample-sbom-context.json) live in Offline Kits and feed the backend self-tests; the CLI fetches evidence from backend services automatically.

Exit codes

Code	Meaning	Notes
0	Success (hit or miss; output cached or freshly generated)	Includes outputHash and citations.
2	Validation error (missing advisory key, bad profile)	Mirrors HTTP 400.
3	Context unavailable (SBOM/LNM/policy missing)	Mirrors HTTP 409 advisory.contextUnavailable.
4	Guardrail block (PII, citation gap, prompt too large)	Mirrors HTTP 422 advisory.guardrail.blocked.
5	Timeout waiting for output	Respect --timeout in seconds (0 = no wait).
12	Remote profile disabled	Returned when cloud-openai is selected without consent.
7	Transport/auth failure	Network/TLS/token issues.

Scripting patterns

• Cache-only probes (CI smoke): stella advise run summary --advisory-key ... --timeout 0 --json > cache.json (fails fast if evidence missing).
• Batch mode: pipe advisory keys: cat advisories.txt | xargs -n1 -I{} stella advise run summary --advisory-key {} --timeout 0 --json.
• Profile gating: set --profile fips-local for offline; use --profile cloud-openai only after Authority consent and when ADVISORYAI__INFERENCE__MODE=Remote.
• Policy pinning: always pass --policy-version (matches Offline Kit bundle hash); outputs include the policy hash in context.planCacheKey.

Sample output (trimmed)

{
  "taskType": "Summary",
  "profile": "fips-local",
  "generatedAt": "2025-11-24T00:00:00Z",
  "outputHash": "sha256:cafe...babe",
  "citations": [{"index":1,"kind":"advisory","sourceId":"concelier:csaf:redhat:RHSA-2025:1001:paragraph:12"}],
  "context": {
    "planCacheKey": "adv-summary:csaf:redhat:RHSA-2025:1001:fips-local",
    "sbom": {"artifactId":"registry.stella-ops.internal/runtime/api","versionTimeline":8,"dependencyPaths":5}
  }
}

Offline kit notes

• Copy the three CLI guardrail artefact bundles and their hashes.sha256 files into offline-kit/advisory-ai/fixtures/ and record them in SHA256SUMS.
• Set ADVISORYAI__SBOM__BASEADDRESS to the SBOM Service endpoint packaged in the kit; leave unset to fall back to NullSbomContextClient (Advisory AI will still respond deterministically with context counts set to 0).
• Keep profiles.catalog.json and prompts.manifest hashes aligned with the guardrail pack referenced in the Offline Kit manifest.

Troubleshooting

• contextUnavailable: ensure SBOM service is reachable or provide --sbom-context fixture; verify LNM linkset IDs and hashes.
• guardrail.blocked: check blocked phrase list (docs/policy/assistant-parameters.md) and payload size; remove PII or reduce SBOM clamps.
• timeout: raise --timeout or run cache-only mode to avoid long waits in CI.