stella auth - Command Guide

Audience: operators and automation owners who authenticate the Stella Ops CLI against Authority.

The stella auth command group handles Authority-backed authentication and token operations: acquiring and caching access tokens, inspecting the active session, minting and delegating service-account tokens, and exporting or verifying revocation bundles. Service clients request their own scoped tokens using configured authentication; a prompted login does not configure their credentials.

Commands

auth login

Acquire and cache an access token using the configured Authority credentials.

stella auth login
stella auth login --force
STELLAOPS_AUTHORITY_CLIENT_ID=stellaops-cli-automation \
stella auth login

Notes:

• --force ignores cached tokens and forces re-authentication.
• Credential sources are configuration-driven (profile/env). This command does not accept raw tokens on the command line.
• When no Authority client ID is configured, the CLI defaults to the seeded human client stellaops-cli.
• In a fresh interactive local/dev shell, auth login prompts for username/password and uses the current password-grant bootstrap path on that human client.
• For non-interactive automation, configure a confidential client such as the seeded local/dev stellaops-cli-automation.

Named service clients used by gate evaluation, exception and release commands do not reuse the prompted auth login cache and do not re-prompt. Configure their authentication before running them:

• Operator password grant: provide STELLAOPS_AUTHORITY_USERNAME and STELLAOPS_AUTHORITY_PASSWORD through the local environment or protected profile configuration.
• Automation: provide STELLAOPS_AUTHORITY_CLIENT_ID and STELLAOPS_AUTHORITY_CLIENT_SECRET for a confidential client with the required owner scopes. The example above assumes its secret is already configured locally.
• An explicitly configured API key takes precedence for clients using ConfigureApiAuthentication.

The reason is cache isolation: StellaOpsBearerTokenHandler keys service tokens by client name, scope, authentication mode, tenant and credential context. auth login uses the separate AuthorityTokenUtilities.BuildCacheKey namespace. The token client implements password and client-credentials requests, and has no refresh-token exchange that connects these caches. A successful prompted login therefore supports session inspection without enabling these service commands on its own. See authentication architecture.

auth status / whoami / logout

stella auth status
stella auth whoami
stella auth logout

Behavior:

• status prints Cached token for <authority> expires at <time>. to stdout; --verbose adds the grant type and scopes.
• whoami prints cached token metadata to stdout without --verbose: authority, grant type, token type, expiry and remaining time, username, scopes (from the token’s scope claim when the token response named none), subject, the token’s own tenant, client ID, audience, issuer and issue time. --verbose adds the remaining claims.
• Without a cached token, or without an Authority URL, status and whoami print the reason to stderr and exit 1.
• login prints Login successful. Access token expires at <time>. to stdout.
• logout removes the auth login entry for the active configuration. Named service clients use separate cache entries; this command does not clear those entries.

auth revoke export / verify

Export or verify Authority revocation bundles.

stella auth revoke export --output ./revocation-export
stella auth revoke verify --bundle ./revocation-bundle.json --signature ./revocation-bundle.json.jws --key ./authority.pub.pem

auth token mint

Mint a service account token (requires appropriate Authority permissions).

stella auth token mint --service-account concelier-jobs \
  --scope concelier.jobs.trigger --scope advisory:ingest --scope advisory:read \
  --tenant tenant-default \
  --reason "scheduled ingestion" \
  --raw

Flags:

• --service-account / -s (required): service account identifier.
• --scope (repeatable, at least one required): scopes to include in the minted token, spelled as in the Authority scope catalogue (for example sbom:read, notify.viewer). There is no default scope.
• --expires-in (optional): expiry in seconds.
• --tenant (optional): tenant context.
• --reason (optional): audit reason.
• --raw: output only the token value (automation-friendly).

auth token delegate

Delegate your current token to another principal.

stella auth token delegate --to user@example.org \
  --scope advisory:read \
  --tenant tenant-default \
  --reason "support session" \
  --raw

Flags:

• --to (required): principal identifier to delegate to.
• --scope (repeatable): delegated scopes (must be a subset of the current token).
• --expires-in (optional): expiry in seconds (defaults to remaining token lifetime).
• --tenant (optional): tenant context.
• --reason (required): audit reason.
• --raw: output only the token value (automation-friendly).

Offline notes

• auth login and token mint/delegate require connectivity to Authority.
• auth revoke verify, status, whoami, and logout can operate using local cached state.

Related

• CLI command reference — complete catalog of stella commands
• stella db — operational commands that require an authenticated session