API and CLI Reference

This is the single entry point for operators and integrators working with the Stella Ops APIs and the stella CLI. Use it to find:

API contracts (OpenAPI, schemas, samples)
CLI command guides and automation-friendly outputs
Cross-cutting conventions (auth, tenancy, errors, determinism, offline posture)

This page is a hub — detailed references live under docs/api/ and docs/modules/cli/. The most-used stella command groups are summarized below; treat the linked OpenAPI documents and command guides as the source of truth.

Command currency: runnable-looking examples that the current CLI parser rejects are explicitly unshipped or stale. Check the machine-enforced baseline before copying an older example into automation.

Quick links

Goal	Open this
API conventions (headers, pagination, errors)	`docs/api/overview.md`
API versioning policy	`docs/api/versioning.md`
Gateway tenancy header policy	`docs/api/gateway/tenant-auth.md`
Gateway header hardening rules	`docs-archive/modules/gateway/identity-header-policy.md`
Console workspaces (findings/VEX views)	`docs/api/console/workspaces.md`
Console search and downloads	`docs/api/console/search-downloads.md`
Exceptions API entry point	`docs/api/exceptions.md`
Download aggregated OpenAPI via CLI	`docs/modules/cli/guides/commands/api.md`
CLI command reference (by command group)	`docs/modules/cli/guides/commands/`
CLI authentication and tokens	`docs/modules/cli/guides/commands/auth.md`
Retired Concelier `db` command record (no running backend)	`docs/modules/cli/guides/commands/db.md`, `docs/CONCELIER_CLI_QUICKSTART.md`
Live vulnerability/advisory operations	`docs/modules/vulnerabilities/architecture.md`, `docs/runbooks/vulnerabilities/vuln-ops.md`
CLI offline/air-gap workflows	`docs/modules/cli/guides/commands/offline.md`, `docs/OFFLINE_KIT.md`
CLI reachability workflow	`docs/modules/cli/guides/commands/reachability.md`
CLI vulnerability workflow	`docs/modules/cli/guides/commands/vuln.md`
Vuln Explorer OpenAPI (v1)	`docs/modules/vuln-explorer/openapi/vuln-explorer.v1.yaml`
Graph Gateway API (draft)	`docs/api/graph.md`, `docs/modules/graph/openapi/graph-gateway-spec-draft.yaml`

CLI command groups documented here

This page documents a curated set of stella commands in detail. Jump to one:

stella system migrations-* — RETIRED — deleted 2026-09-14; migrations converge per service at host start
stella scan diff— ELF binary diff between two images
stella guard run— AI code guard checks
stella image inspect— OCI image manifest/layer inspection
stella setup— installation-scoped control-plane bootstrap
stella config integrations bootstrap local— local Compose fixture catalog
stella advise ask/ chat-doctor/ chat-settings/ export— AdvisoryAI assistant
stella search/ stella doctor suggest— knowledge search and diagnostics
stella advisoryai index rebuild/ sources prepare— AKS index maintenance

For the full command surface (one guide per command group), see docs/modules/cli/guides/commands/.

Where the API contracts live

Stella Ops treats the OpenAPI documents and JSON schemas as the source of truth for HTTP shapes.

Aggregation/discovery: docs/api/openapi-discovery.md
Gateway-proxied reference docs + samples: docs/api/gateway/
Service-specific OpenAPI (selected):
- docs/modules/platform/openapi/artifact-store-api.yaml
- docs/modules/scanner/openapi/delta-compare-openapi.yaml
- docs/modules/findings/openapi/v1.json (the live Findings surface; the Evidence & Decision design record is frozen at docs-archive/modules/findings/openapi/evidence-decision-api.openapi.yaml)
- docs/modules/policy/openapi/gates-api.yaml
- docs/modules/graph/openapi/graph-gateway-spec-draft.yaml
- docs/modules/notify/openapi/notify-openapi.yaml
- docs/modules/attestor/openapi/proofs-openapi.yaml
API samples and fixtures (deterministic): docs/api/**/samples/

If you are building an SDK or want a single document for tooling, prefer the CLI OpenAPI download flow:

stella api spec list
stella api spec download --output ./openapi.yaml --format openapi-yaml

See: docs/modules/cli/guides/commands/api.md.

Where the CLI docs live

The stella CLI is documented as:

High-level module docs: docs/modules/cli/README.md, docs/modules/cli/architecture.md
Command guides: docs/modules/cli/guides/commands/ (one file per command group)

CLI docs are written to match repo reality; avoid copying raw endpoint paths into the CLI guides unless they are backed by OpenAPI and tests.

Cross-cutting conventions (high-level)

For the detailed contract, see docs/api/overview.md. The stable rules to keep in mind:

Auth: bearer tokens are the baseline; sender-constrained modes (DPoP/mTLS) are deployment-profile dependent.
Tenancy: every tenant-scoped request must carry an explicit tenant context (see docs/api/gateway/tenant-auth.md).
Determinism: stable ordering, stable ids, UTC ISO-8601 timestamps, and canonical hashing where applicable.
Streaming: some endpoints use NDJSON (application/x-ndjson) for deterministic, resumable tile/record streams.
Offline-first: workflows must remain runnable in air-gapped mode using Offline Kit bundles and locally verifiable signatures.

stella system migrations commands — RETIRED

Retired (SPRINT_20260722_021 PLT-4, DC-26, 2026-09-14). The whole stella system command group (migrations-run, migrations-status, migrations-verify) was deleted together with the central migration-plugin mechanism it drove (IMigrationModulePlugin, plugin-directory and STELLAOPS_MIGRATION_PLUGIN* discovery, MigrationModuleRegistry, ReleaseMigrationRunner). The CLI no longer references StellaOps.Platform.Persistence. There is no manual or DR migration applier.

(The heading avoids / on purpose: slash characters produce different heading anchors in different Markdown renderers, which silently breaks the table-of-contents link above.)

What replaces it

Convergence. Every service converges its own database from its own embedded Startup-band SQL (001–099) at host start (AddStartupMigrations); one service = one database + own role (ADR-039). To apply a new migration, deploy the owning service and restart it. No operator step exists in steady state.
Status. Each service’s db.migration-status doctor check (GET /doctor/<service>/checks), or the owning schema’s <schema>.schema_migrations table read through psql.
Checksums. Validated by the owning host on every boot; genuine drift fails closed. Recovery is docs/runbooks/database/migration-recovery.md.
Release (100+ or rollback in the name) and Data (DM-prefixed) categories must not exist. NoManualCategoryMigrationsTests guards the tree. If one appears, the owning StartupMigrationHost fails closed: renumber the file into the Startup band so the owning host applies it, or apply it by hand per the recovery runbook and record the ledger row.
Seed (S-prefixed) migrations run only when the owning module’s bootstrap flag is enabled (<MODULE>_BOOTSTRAP_ENABLED=true), never through a CLI.

Platform Migration Admin API — RETIRED

Retired (SPRINT_20260722_026 CM-2, 2026-08-02). The central migration admin API (/api/v1/admin/migrations/*) and /api/v1/admin/seed-demo no longer exist — the endpoints, the gateway route, and their tests were deleted. Migration status is each service’s own doctor db.migration-status check (GET /doctor/<service>/checks); schema convergence is each service’s startup migrations. The local CLI applier that survived this retirement was itself deleted on 2026-09-14 (see above).

`admin seed-demo` — REMOVED

Removed (SPRINT_20260722_026 CM-2, 2026-08-18). This command was a third face of the central migrator that the 2026-08-02 retirement missed: before seeding it ran startup-category migrations for every module in MigrationModuleRegistry against one connection, so --confirm — documented as confirming demo-data insertion — also authorised central cross-database schema convergence. Its demo half had already been made inert by the §2.11 purge (every S001_demo_seed.sql now sits under _archived/ and is not embedded). There is no replacement and none is needed: schema convergence is each service’s startup migrations (§2.7) and the sanctioned QA seeding path is stella qa-seed. The stella system migrations-* group that this note used to name as the manual DR applier was deleted on 2026-09-14 (SPRINT_20260722_021 PLT-4); MigrationModuleRegistry went with it.

stella scan diff

Compare ELF binaries between two container images using section hashes.

Synopsis

stella scan diff --base <image-ref> --target <image-ref> [options]

Options

Option	Description
`--base`, `-b`	Base image reference (tag or digest).
`--target`, `-t`	Target image reference (tag or digest).
`--mode`, `-m`	Analysis mode: `elf`, `pe`, `auto` (default: `auto`, currently uses ELF).
`--emit-dsse`, `-d`	Directory for DSSE attestation output.
`--signing-key`	Path to ECDSA private key (PEM) for DSSE signing.
`--format`, `-f`	Output format: `table`, `json`, `summary` (default: `table`).
`--platform`, `-p`	Platform filter (e.g., `linux/amd64`).
`--include-unchanged`	Include unchanged binaries in output.
`--sections`	Sections to analyze (comma-separated or repeatable).
`--registry-auth`	Path to Docker config for registry authentication.
`--timeout`	Timeout in seconds (default: 300).
`--verbose`, `-v`	Enable verbose output.

Note: --emit-dsse requires --signing-key to sign the DSSE envelope.

Examples

# Basic comparison
stella scan diff --base myapp:1.0.0 --target myapp:1.0.1

# DSSE output with signing key
stella scan diff --base myapp:1.0.0 --target myapp:1.0.1 \
  --mode=elf --emit-dsse=./attestations --signing-key=./keys/binarydiff.pem

# JSON output for automation
stella scan diff --base myapp:1.0.0 --target myapp:1.0.1 --format=json > diff.json

# Specific platform
stella scan diff --base myapp:1.0.0 --target myapp:1.0.1 --platform=linux/amd64

Output

DSSE output produces two files per platform:

attestations/
  linux-amd64-binarydiff.dsse.json
  linux-amd64-binarydiff.payload.json

See also: docs/modules/scanner/binary-diff-attestation.md.

stella guard run

Collect bounded source files and run the server-owned Integrations AI Code Guard analysis. The CLI is a thin adapter that gathers bounded source input and posts it. It does not implement analyzers.

Synopsis

stella guard run [<path>] [options]
stella guard status [--format json|text]

<path> is the source file or directory to submit. It defaults to ..

Options (`run`)

Option	Description
`--policy`, `-p`	AI Code Guard YAML configuration file (conventionally `.stellaops.yml`).
`--format`, `-f`	Output format: `json` (default), `text`, `sarif`, `gitlab`.
`--output`, `-o`	Write the report to a file instead of stdout.
`--owner`	Repository owner sent to the Integrations contract (default: `local`).
`--repo`	Repository name (defaults to the target directory or file name).
`--commit`	Commit SHA or immutable revision identifier (default: `working-tree`).
`--exclude`, `-e`	Simple wildcard path patterns to exclude (repeatable).
`--server`	Integrations API base URL override.
`--sealed`	Reserved for a future offline analyzer bundle; currently fails closed.
`--verbose`, `-v`	Enable verbose output.

Options (`status`)

Option	Description
`--format`, `-f`	Output format: `json` (default) or `text`.
`--verbose`, `-v`	Enable verbose output.

stella guard status describes the CLI/server contract only. It does not call the server, so it reports liveReadinessChecked: false and never proves that the backend is reachable.

Collection bounds

run fails closed rather than truncating. It refuses any single source or policy file over 1 MiB, a total payload over 10 MiB, more than 1000 collected files, or more than 10000 traversed entries. .git, .nuget, bin, node_modules, obj and vendor directories are skipped, and symlinks and junctions are never followed.

Exit codes

Code	Meaning
`0`	Pass
`1`	Warning or fail findings
`10`	Input error (bad path, bad format, no eligible files, `--sealed`)
`11`	Network error
`12`	Analysis error (pending or error status)
`99`	Unknown error

Examples

# Analyse the working tree and write SARIF
stella guard run --policy .stellaops.yml --format sarif --output guard.sarif

# Analyse one directory, attributed to a commit, excluding fixtures
stella guard run ./src --owner acme --repo billing --commit "$GIT_SHA" --exclude "**/testdata/*"

# Describe the contract without calling the server
stella guard status --format text

stella image inspect

Inspect OCI image manifests and layers.

Synopsis

stella image inspect <reference> [options]

Options

Option	Description
`--resolve-index`, `-r`	Resolve multi-arch index to platform manifests (default: true).
`--print-layers`, `-l`	Include layer details in output (default: true).
`--platform`, `-p`	Platform filter (e.g., `linux/amd64`).
`--output`, `-o`	Output format: `table`, `json` (default: `table`).
`--timeout`	Timeout in seconds (default: 60).
`--verbose`, `-v`	Enable verbose output.

Examples

# Basic inspection
stella image inspect nginx:latest

# JSON output
stella image inspect nginx:latest --output json

# Filter to a single platform
stella image inspect nginx:latest --platform linux/amd64

# Local registry over HTTP
stella image inspect http://localhost:5000/myapp:1.0.0

Exit codes

Code	Meaning
`0`	Success
`1`	Image not found
`2`	Error (auth, network, invalid input, timeout)

stella setup

Installation-scoped control-plane bootstrap for the running StellaOps platform.

Synopsis

stella setup [--config <path>] [--non-interactive]
stella setup run [options]
stella setup resume [--session <id>]
stella setup status [--session <id>] [--json]
stella setup reset [--step <step-id> | --all] [--force]
stella setup validate --config <path>

Options

Options are scoped to the command that declares them. They are not inherited by subcommands: --config and --non-interactive belong to bare stella setup (and --config to validate), so stella setup run --config <path> is rejected with Unrecognized command or argument '--config'.

Option	Where it is accepted	Description
`--config`, `-c`	`setup`, `validate`	Path to the YAML configuration file used to seed setup draft values. Required by `validate`.
`--non-interactive`, `-y`	`setup`	Run without prompts.
`--step`, `-s`	`run`, `reset`	Limit the operation to one supported control-plane step.
`--skip`	`run`	Skip the named steps. Repeatable.
`--dry-run`	`run`	Validate configuration without applying changes.
`--force`, `-f`	`run`, `reset`	`run` re-runs already completed steps; `reset` skips confirmation prompts.
`--all`	`reset`	Reset all setup state.
`--session`	`resume`, `status`	Use an explicit session id instead of the latest.
`--json`	`status`	Emit machine-readable session state with sanitized `draftValues` and retained-secret `secretDrafts` metadata.
`--verbose`, `-v`	all	Enable verbose output.

Available Steps

Step ID	Name	Required	Description
`database`	PostgreSQL Database	Yes	Configure database connection.
`cache`	Valkey/Redis Cache	Yes	Configure cache connection.
`migrations`	Database Migrations	Yes	Converge the required schema migrations.
`admin`	Admin Bootstrap	Yes	Ensure the bootstrap administrator exists.
`crypto`	Crypto Profile	Yes	Validate and apply the selected crypto profile.

The pre-release step aliases valkey, authority, and users were removed; --step and --skip accept only the step IDs above and reject unknown names.

Former setup targets such as vault, settingsstore, registry, scm, notify, telemetry, llm, sources, environments, and agents are not setup steps: --step and --skip reject them as unknown step names, like any other unknown name. Configure those integrations on the authenticated onboarding surfaces after bootstrap.

Examples

# Run the installation bootstrap
stella setup run

# Probe one step only
stella setup run --step database --dry-run

# Seed draft values from a config file (--config belongs to bare `setup`, not to `run`)
stella setup --config ./setup.yaml --non-interactive

# Check a config file without running setup
stella setup validate --config ./setup.yaml

# Resume and inspect status
stella setup resume
stella setup status --json

# Reset the installation session
stella setup reset --all --force

stella setup reset resets installation-session state only. It does not reset, rotate, or unlock an existing Authority admin password. For local compose source-checkout recovery, use devops/compose/scripts/authority-password-set.ps1 or authority-password-set.sh.

After stella setup, use the authenticated integration/onboarding surfaces instead of more setup steps:

stella config integrations bootstrap local
stella config integrations bootstrap local --include-gitlab
stella config integrations bootstrap local --include-gitlab --include-gitlab-registry

# Production or customer-managed systems still use BYO-secret onboarding
stella config integrations secrets targets
stella config integrations secrets upsert-bundle \
  --bundle gitlab-server \
  --target <vault-integration-id> \
  --path gitlab/server \
  --entry access-token=glpat-...

Setup-session secret handling:

Session reads never return plaintext secret values.
Retained setup secrets surface only as secretDrafts metadata and are reused server-side during resume/apply.

stella config integrations bootstrap local

Bootstrap the Stella-owned local compose fixture catalog from the CLI.

Synopsis

stella config integrations bootstrap local [--include-gitlab] [--include-gitlab-registry] [--format table|json]

Options

Option	Description
`--include-gitlab`	Include the owned local GitLab Server and GitLab CI fixtures. The CLI mints and stages the local PAT into Vault automatically.
`--include-gitlab-registry`	Include the optional local GitLab container registry fixture. Requires the heavy GitLab compose profile with `GITLAB_ENABLE_REGISTRY=true`.
`--format`	Output format: `table` or `json` (default: `table`).
`--verbose`, `-v`	Enable verbose output.

Examples

# Default 13-entry local fixture catalog
stella config integrations bootstrap local

# Add GitLab Server and GitLab CI
stella config integrations bootstrap local --include-gitlab

# Add the optional GitLab registry and emit machine-readable results
stella config integrations bootstrap local --include-gitlab --include-gitlab-registry --format json

Contract

This command is for Stella-owned local compose fixtures only.
Default mode creates or updates 13 deterministic local integrations and verifies both connector test and runtime health for each selected entry.
--include-gitlab stages the owned local GitLab PAT through Secret Authority and binds the returned authref://vault/gitlab#access-token value to GitLab Server and GitLab CI.
--include-gitlab-registry stages and binds authref://vault/gitlab#registry-basic for the optional local GitLab registry surface, which must be started with GITLAB_ENABLE_REGISTRY=true.
Exit code 0 means every selected integration tested healthy and reported healthy runtime status. Exit code 1 means bootstrap or verification failed.
For production or customer-managed systems, use stella config integrations secrets targets, stella config integrations secrets upsert-bundle, and explicit create or update operations with operator-provided credentials.

stella advise ask

Ask questions to the AdvisoryAI assistant.

Synopsis

stella advise ask <query> [options]

Options

Option	Description
`--image`, `-i`	Container image reference to scope the query.
`--digest`, `-d`	Artifact digest to scope the query.
`--environment`, `-e`	Environment context (e.g., production, staging).
`--conversation-id`, `-c`	Conversation ID for follow-up queries.
`--file`	Read batch queries from newline-delimited JSON (`.jsonl`).
`--format`, `-f`	Output format: `table`, `json`, `markdown`.
`--output`, `-o`	Write output to file.
`--tenant`	Tenant to act in (see Tenant selection).
`--verbose`, `-v`	Enable verbose output.

Tenant selection. Every advise chat verb (ask, chat-doctor, chat-settings get|update|clear, export) takes --tenant, sent as the X-StellaOps-TenantId header. The router gateway honours it for a global administrator (ADR-023) and, when its tenant override is enabled, for a tenant in the token’s stellaops:allowed_tenants; it signs the selected tenant into the identity envelope that AdvisoryAI reads. Any other caller stays in the token’s tenant. No chat verb has a --user option: AdvisoryAI takes the user from the identity envelope’s subject only, so chat settings with --scope user and conversations always belong to the signed-in user.

AdvisoryAI always returns the evidence links it assembled, and proposed actions are suggestions that the CLI never executes; ask has no option to change either.

Prerequisites

AdvisoryAI owns model readiness; the CLI needs no local model keys. When the chat runtime is unavailable, ask prints Chat service unavailable: <reason> and exits non-zero. Run stella advise chat-doctor to see the model gateway status.

Examples

# Basic query
stella advise ask "What vulnerabilities affect CVE-2024-1234?"

# Scoped to an image
stella advise ask "Is this image safe for production?" --image myapp:1.0.0

# Scoped to an artifact digest
stella advise ask "Explain the risk of log4j in this artifact" \
  --digest sha256:abc123...

# JSON output for automation
stella advise ask "List critical vulnerabilities" --format json > report.json

stella advise chat-doctor

Check AdvisoryAI chat quota and configuration status.

Synopsis

stella advise chat-doctor [options]

Options

Option	Description
`--format`, `-f`	Output format: `table`, `json`.
`--output`, `-o`	Write output to file.
`--tenant`	Tenant to act in (see Tenant selection).
`--verbose`, `-v`	Enable verbose output.

Examples

# Check configuration status
stella advise chat-doctor

# JSON output
stella advise chat-doctor --format json

stella advise chat-settings

Manage AdvisoryAI chat settings and quotas.

Synopsis

stella advise chat-settings get [options]
stella advise chat-settings update [options]
stella advise chat-settings clear [options]

Get Options

get (and bare chat-settings) shows the effective settings: the global defaults with the tenant overrides and the signed-in user’s overrides applied. AdvisoryAI has no per-scope read, so get takes no --scope.

Option	Description
`--format`, `-f`	Output format: `table`, `json`.
`--output`, `-o`	Write output to file.
`--tenant`	Tenant to act in (see Tenant selection).

Update Options

Option	Description
`--scope`, `-s`	Settings scope: `user`, `tenant` (default: `user`).
`--requests-per-minute`	Set requests per minute quota.
`--requests-per-day`	Set requests per day quota.
`--tokens-per-day`	Set tokens per day quota.
`--tool-calls-per-day`	Set tool calls per day quota.
`--allow-all-tools`	Allow all tools (true/false).
`--allowed-tools`	Set allowed tools (comma-separated).
`--format`, `-f`	Output format: `table`, `json`.
`--tenant`	Tenant to act in (see Tenant selection).

Clear Options

Option	Description
`--scope`, `-s`	Settings scope: `user`, `tenant` (default: `user`).
`--tenant`	Tenant to act in (see Tenant selection).

--scope user always addresses the signed-in user’s own overrides.

Examples

# View effective settings
stella advise chat-settings get

# View effective settings as JSON
stella advise chat-settings get --format json

# Update quotas
stella advise chat-settings update --requests-per-day 100

# Clear user overrides
stella advise chat-settings clear --scope user

stella advise export

Export AdvisoryAI conversation history.

Synopsis

stella advise export [options]

Options

Option	Description
`--conversation-id`, `-c`	Export one conversation. Without it, the command lists the signed-in user’s conversations and exports each one.
`--tenant`	Tenant to act in (see Tenant selection).
`--limit`	Maximum number of conversations to export (default: 100).
`--format`, `-f`	Output format: `json`, `table`, `markdown` (default: `json`).
`--output`, `-o`	Write the export to a file.
`--verbose`, `-v`	Enable verbose output.

Each exported conversation carries the tenantId and userId that AdvisoryAI stored with it. The export’s top-level tenantId repeats the --tenant value when one was given.

Examples

# Export your conversations as JSON
stella advise export --output conversations.json

# Export one conversation as Markdown
stella advise export --conversation-id conv-123 --format markdown

stella search

Search AdvisoryAI Knowledge Search (AKS) across docs, API operations, and Doctor checks.

Synopsis

stella search "<query>" [options]

Options

Option	Description
`--type`	Result type filter: `docs`, `api`, `doctor` (repeatable or comma-separated).
`--product`	Product filter.
`--version`	Version filter.
`--service`	Service filter (especially for API operations).
`--tag`	Tag filter (repeatable or comma-separated).
`--k`	Top result count (`1..100`).
`--json`	Emit stable machine-readable payload.
`--verbose`, `-v`	Include debug scoring fields when available.

Examples

stella search "docker login fails with x509 unknown authority"
stella search "endpoint for agent registration token" --type api --json
stella search "OIDC readiness checks" --type doctor --k 20

stella doctor suggest

Use AKS to suggest Doctor checks, docs, and API references for a symptom string.

Synopsis

stella doctor suggest "<symptom-or-error>" [options]

Options

Option	Description
`--product`	Product filter.
`--version`	Version filter.
`--k`	Top result count (`1..100`).
`--json`	Emit stable machine-readable payload.
`--verbose`, `-v`	Include debug scoring fields when available.

Examples

stella doctor suggest "database unavailable and timeout expired"
stella doctor suggest "gateway returns 404 on known route" --json

stella advisoryai index rebuild

Local repo build and use of the Stella CLI

When working from this repository, do not assume stella is already installed on PATH. Use one of these local workflows first:

# Run the CLI directly from source
dotnet run --project "src/Cli/StellaOps.Cli/StellaOps.Cli.csproj" -- --help

# Publish a reusable local binary
dotnet publish "src/Cli/StellaOps.Cli/StellaOps.Cli.csproj" -c Release -o ".artifacts/stella-cli"

# Windows
.artifacts/stella-cli/StellaOps.Cli.exe --help

# Linux/macOS
./.artifacts/stella-cli/StellaOps.Cli --help

Related docs:

CLI quickstart: docs/modules/cli/guides/quickstart.md
AdvisoryAI live test setup: src/AdvisoryAI/__Tests/INFRASTRUCTURE.md

Rebuild the AdvisoryAI deterministic knowledge index from local markdown, OpenAPI specs, and Doctor metadata.

Local source-checkout note:

stella advisoryai index rebuild calls an authenticated backend endpoint.
For the unauthenticated local live-search verification lane, use stella advisoryai sources prepare plus the direct HTTP rebuild calls documented in src/AdvisoryAI/__Tests/INFRASTRUCTURE.md.

Synopsis

stella advisoryai index rebuild [--json] [--verbose]

Examples

stella advisoryai index rebuild
stella advisoryai index rebuild --json

stella advisoryai sources prepare

Prepare OpenAPI and Doctor source artifacts for AdvisoryAI Knowledge Search (AKS) index rebuild. Doctor controls output is enriched from configured seed plus locally discovered Doctor checks (when Doctor engine services are available), providing fallback metadata for AdvisoryAI ingestion.

Generate the reviewed docs manifest separately with python tools/scripts/validate/check-advisoryai-docs-manifest.py --write. The CLI does not write that manifest or enumerate Markdown pages.

Requirements:

In a source checkout, do not assume stella is already installed on PATH; build or run it from source first.
Set STELLAOPS_BACKEND_URL (or the equivalent CLI config file value), including when reusing an existing OpenAPI snapshot. Normal online settings are required before the cache is read.
A structurally valid OpenAPI snapshot is reused unless --overwrite is supplied, with fromCache=true reported. An empty cache or --overwrite fetches the Gateway’s merged /openapi.json document; configure the Gateway URL for fresh retrieval. Failed retrieval preserves good OpenAPI output and stops before Doctor controls are written. The API command guide describes owner routes, service selection and cache verification.

Synopsis

stella advisoryai sources prepare [options]

Options

Option	Description
`--repo-root`	Repository root used to resolve source paths.
`--openapi-output`	Output path for aggregated OpenAPI JSON artifact.
`--doctor-seed`	Input doctor seed JSON path.
`--doctor-controls-output`	Output path for doctor controls projection JSON (controls + fallback metadata).
`--overwrite`	Overwrite existing output files.
`--json`	Emit stable machine-readable summary.

Examples

export STELLAOPS_BACKEND_URL="http://127.0.0.1:10451"
python tools/scripts/validate/check-advisoryai-docs-manifest.py --write
stella advisoryai sources prepare --json
stella advisoryai sources prepare --repo-root . --openapi-output devops/compose/openapi_current.json