Released-site CLI operator quickstart

Use this guide when Stella Ops is already released or deployed somewhere and you need to operate it from the CLI without a source checkout.

Pick the runner

Situation	Use
You have a compose-based Stella Ops deployment	`devops/compose/scripts/stella-cli.sh` or `devops/compose/scripts/stella-cli.ps1`
You only have Docker and the published CLI image	`docker run --rm registry.example.com/stellaops/cli:<version> ...`
You are developing from this repository	`dotnet run --project src/Cli/StellaOps.Cli/StellaOps.Cli.csproj -- ...`

The source-free CLI image is the release artifact for deployed sites. It must be published with the service images and must contain the restart-time CLI plug-in payload under /app/plugins/cli.

Required environment

Set these values before using the source-free runner:

Variable	Purpose	Typical value
`STELLAOPS_CLI_IMAGE`	CLI image to run	`registry.example.com/stellaops/cli:<release-version>`
`STELLAOPS_BACKEND_URL`	Router or backend URL reachable from the CLI container	`http://router.stella-ops.local:8080`
`STELLAOPS_AUTHORITY_URL`	Authority URL reachable from the CLI container	`http://authority.stella-ops.local:8440`
`STELLAOPS_AUTHORITY_CLIENT_ID`	Authority client id	`stellaops-cli` for human/bootstrap use, `stellaops-cli-automation` for automation
`STELLAOPS_AUTHORITY_CLIENT_SECRET`	Secret for confidential automation clients	Deployment secret value
`STELLAOPS_AUTHORITY_USERNAME`	Human/admin username when using password grant	`admin`
`STELLAOPS_AUTHORITY_PASSWORD`	Human/admin password when using password grant	Private deployment secret
`STELLAOPS_CLI_WORKDIR`	Host directory mounted as `/workspace`	Directory containing setup YAML or operator inputs

The compose overlay stores CLI token/cache state in a dedicated stella-cli-state volume. Operator inputs should live under the mounted workspace and be referenced as /workspace/<file>.

Compose shortcut

Bash:

cd devops/compose
export STELLAOPS_CLI_IMAGE=registry.example.com/stellaops/cli:<release-version>
export STELLAOPS_CLI_WORKDIR="$PWD"
export STELLAOPS_BACKEND_URL=http://router.stella-ops.local:8080
export STELLAOPS_AUTHORITY_URL=http://authority.stella-ops.local:8440
export STELLAOPS_AUTHORITY_CLIENT_ID=stellaops-cli
export STELLAOPS_AUTHORITY_USERNAME=admin
export STELLAOPS_AUTHORITY_PASSWORD='<admin-password>'

./scripts/stella-cli.sh setup status --json

PowerShell:

cd devops/compose
$env:STELLAOPS_CLI_IMAGE = 'registry.example.com/stellaops/cli:<release-version>'
$env:STELLAOPS_CLI_WORKDIR = (Resolve-Path .).Path
$env:STELLAOPS_BACKEND_URL = 'http://router.stella-ops.local:8080'
$env:STELLAOPS_AUTHORITY_URL = 'http://authority.stella-ops.local:8440'
$env:STELLAOPS_AUTHORITY_CLIENT_ID = 'stellaops-cli'
$env:STELLAOPS_AUTHORITY_USERNAME = 'admin'
$env:STELLAOPS_AUTHORITY_PASSWORD = '<admin-password>'

.\scripts\stella-cli.ps1 setup status --json

Run setup with a workspace file:

./scripts/stella-cli.sh setup run --config /workspace/setup.yaml --non-interactive

Run admin password reset from a released CLI image only when that image is already inside the Authority environment and the command has the required Authority storage access:

printf '%s\n' 'Admin@Stella2026!' |
  ./scripts/stella-cli.sh admin users password-set admin \
    --confirm-authority-access \
    --password-stdin

For a local source checkout with the compose stack running, use the dedicated Authority recovery helper instead. It publishes the current Stella CLI, runs a one-shot container on the Stella compose network, and passes the password through stdin:

$env:STELLAOPS_ADMIN_PASS = '<new-private-password>'
$env:STELLAOPS_ADMIN_PASS |
  .\scripts\authority-password-set.ps1 -Username admin -Tenant default -PasswordStdin

Direct Docker runner

Use direct Docker when compose files are not present:

docker run --rm -it \
  -e STELLAOPS_BACKEND_URL=https://stella.example.com \
  -e STELLAOPS_AUTHORITY_URL=https://authority.example.com \
  -e STELLAOPS_AUTHORITY_CLIENT_ID=stellaops-cli \
  -e STELLAOPS_AUTHORITY_USERNAME=admin \
  -e STELLAOPS_AUTHORITY_PASSWORD='<admin-password>' \
  -v "$PWD:/workspace" \
  registry.example.com/stellaops/cli:<release-version> \
  setup status --json

For automation, use the confidential client instead:

docker run --rm \
  -e STELLAOPS_BACKEND_URL=https://stella.example.com \
  -e STELLAOPS_AUTHORITY_URL=https://authority.example.com \
  -e STELLAOPS_AUTHORITY_CLIENT_ID=stellaops-cli-automation \
  -e STELLAOPS_AUTHORITY_CLIENT_SECRET='<client-secret>' \
  registry.example.com/stellaops/cli:<release-version> \
  setup status --json

Verify the image is complete

Before trusting a newly published CLI image, check both core help and plug-in-only command groups:

docker run --rm registry.example.com/stellaops/cli:<release-version> --help
docker run --rm registry.example.com/stellaops/cli:<release-version> runtime --help
docker run --rm registry.example.com/stellaops/cli:<release-version> excititor --help
docker run --rm registry.example.com/stellaops/cli:<release-version> offline kit --help

Expected restart-time plug-ins in /app/plugins/cli:

Aoc
GroundTruth
NonCore
Policy
Symbols
Timestamp
Verdict
Vex

The loader intentionally skips duplicate root commands that are already provided by the core CLI. A release check that only runs stella --help is not enough; also check runtime, excititor, and offline kit.

Troubleshooting

Symptom	Check
`setup status` cannot reach services	Confirm `STELLAOPS_BACKEND_URL` is reachable from inside the CLI container. In compose, use service DNS names such as `router.stella-ops.local`.
Authority login fails	Confirm `STELLAOPS_AUTHORITY_URL`, client id, username/password or client secret, and tenant/scope settings.
Existing local `admin` password is stale or unknown	In a source checkout, use `devops/compose/scripts/authority-password-set.ps1`; do not wipe databases, edit `authority.users`, or enable demo seed.
`authority-password-set.*` publish reports `MSB3541` and `Null character in path`	Generated MSBuild `obj` state is corrupt. The current helper runs publish with build servers disabled, removes only the named generated `obj` directory inside the repo, and retries once.
Plug-in commands are missing	Confirm the image has `/app/plugins/cli/**` manifests and assemblies, and `STELLAOPS_CLI_PLUGIN_BASE_DIRECTORY=/app`.
Workspace files are not found	Put files under `STELLAOPS_CLI_WORKDIR` and reference them as `/workspace/<file>` from CLI arguments.
Docker network is missing	Start the Stella Ops compose stack first, or point backend/Authority URLs at externally reachable endpoints.

Deeper references

CLI module entry: …/README.md
Distribution matrix: distribution-matrix.md
Compose source-free runner: …/…/…/…/devops/compose/README.md#source-free-cli-runner
CLI image build notes: …/…/…/…/devops/docker/README.md#cli-image