# stella auth - Command Guide

The `stella auth` command group manages Authority-backed authentication and token operations used by other CLI commands.

## Commands

### auth login

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

```bash
stella auth login
stella auth login --force
```

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.

### auth status / whoami / logout

```bash
stella auth status
stella auth whoami
stella auth logout
```

Behavior:
- `status` reports whether a cached token exists and whether it is still valid.
- `whoami` prints cached token claims (subject, scopes, expiry) for diagnostics.
- `logout` removes cached tokens for the active credentials.

### auth revoke export / verify

Export or verify Authority revocation bundles.

```bash
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).

```bash
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): scopes to include in the minted token.
- `--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.

```bash
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.