Advisory AI CLI Usage

Audience: CI authors and operators driving Advisory AI from the command line, especially in offline and air-gapped pipelines.

This guide shows how to drive Advisory AI from the Stella Ops CLI (stella) using the advise run verb, with deterministic fixtures (CLI-VULN-29-001, CLI-VEX-30-001). It is designed for CI and offline use, and mirrors the guardrail and policy contracts captured in Guardrails and evidence and Policy assistant parameters.

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

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. NullSbomContextClient is not a production default; it may only bind in an explicit Development/Testing local harness with AdvisoryAI:RuntimeBindings:AllowLocalHarnessFakes=true.
• 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 the blocked-phrase list (see Policy assistant parameters) and payload size; remove PII or reduce SBOM clamps.
• timeout: raise --timeout or run cache-only mode to avoid long waits in CI.