stella CLI — Task Pack SSO Profiles

Current implementation status (verified 2026-07-18): this page describes the intended profile workflow, not a supported current CLI contract. The CLI persists generic profiles in ~/.stellaops/profiles.json, but --profile/STELLA_PROFILE does not currently compose a selected Task Pack role bundle into Authority token scopes, and token cache keys do not include profile identity. Until the feature is implemented, configure the Authority scope explicitly and do not assume two named profiles with identical authority, credential, and scope are cache-isolated.

This guide is for operators and CI engineers who run, publish, or approve Task Packs through the stella CLI and want each role to log in with exactly the right Authority scopes.

Task Pack workflows rely on purpose-scoped Authority clients. To streamline local logins and CI/CD automation, define Stella Ops CLI profiles under ~/.stellaops/profiles so stella auth login automatically requests the correct scopes.

Profiles are simple YAML files that map onto the CLI configuration schema. Set STELLA_PROFILE=<name> (or pass --profile <name> once the CLI exposes the switch) before invoking stella to load the profile.

Example profiles

Packs operator (~/.stellaops/profiles/packs-operator.yaml)

StellaOps:
  Authority:
    Url: https://authority.example.com
    ClientId: pack-operator
    ClientSecretFile: ~/.stellaops/secrets/pack-operator.secret
    Scope: "packs.read packs.run"
    TokenCacheDirectory: ~/.stellaops/tokens
  BackendUrl: https://task-runner.example.com

Packs publisher (~/.stellaops/profiles/packs-publisher.yaml)

StellaOps:
  Authority:
    Url: https://authority.example.com
    ClientId: packs-registry
    ClientSecretFile: ~/.stellaops/secrets/packs-registry.secret
    Scope: "packs.read packs.write"
    TokenCacheDirectory: ~/.stellaops/tokens
  BackendUrl: https://packs-registry.example.com

Packs approver (~/.stellaops/profiles/packs-approver.yaml)

StellaOps:
  Authority:
    Url: https://authority.example.com
    ClientId: pack-approver
    ClientSecretFile: ~/.stellaops/secrets/pack-approver.secret
    Scope: "packs.read packs.approve"
    TokenCacheDirectory: ~/.stellaops/tokens
  BackendUrl: https://task-runner.example.com

Usage

  1. Create the profile file under ~/.stellaops/profiles/<name>.yaml.
  2. Store the matching client secret in the referenced path (or set ClientSecret for development).
  3. Export STELLA_PROFILE=<name> before running stella auth login or individual pack commands.

The CLI reads the profile, applies the Authority configuration, and requests the listed scopes so the resulting tokens satisfy Task Runner and Packs Registry expectations.

Pack approval tip – stella pack approve relays --pack-run-id, --pack-gate-id, and --pack-plan-hash to Authority whenever it asks for packs.approve. Profiles don’t store these values (they change per run), but keeping the approver profile loaded ensures the CLI can prompt for the metadata, validate it against the plan hash, and satisfy the Authority approvals procedure for the Packs Registry.