# StellaOps Authority — CLI Team

> **Read first:** `AGENTS.md`, `StellaOps.Authority.TODOS.md`, and this plan. Keep status aligned in all trackers.

## Mission
Enable `stellaops-cli` to authenticate against StellaOps Authority, manage tokens, and surface auth-related UX for operators.

## Task Queue

| Order | Task IDs | Description | Dependencies | Acceptance |
|-------|----------|-------------|--------------|------------|
| 1 | CLI1 | Extend `StellaOpsCliOptions` and configuration bootstrap to include Authority settings (AuthorityUrl, ClientId/Secret, Username/Password). | LIB4 | **DONE (2025-10-10)** – Options bind authority fields, env fallbacks documented, and cache directory defaults to `~/.stellaops/tokens`. |
| 2 | CLI2 | Implement `auth` command group (`login`, `logout`, `status`) using `StellaOps.Auth.Client`. | CLI1, LIB4 | **DONE (2025-10-10)** – Commands support client-credentials/password flows, force re-auth, and surface status output. |
| 3 | CLI3 | Ensure all backend calls attach bearer tokens; handle 401/403 with clear messaging and retry guidance. | CLI2, LIB2 | **DONE (2025-10-10)** – Backend client now resolves cached tokens via shared helper and attaches Authorization headers on every call. |
| 4 | CLI4 | Update help text and docs (quickstart + API reference) to describe new auth workflow. | CLI1–CLI3 | Coordinate with Docs team for final copy. |
| 5 | OPTIONAL | Add `auth whoami` to display token scopes/expiry (post-MVP if time allows). | CLI2 | Non-blocking enhancement. |

## Implementation Notes
- Token cache path defaults to `~/.stellaops/tokens`; allow override via config.  
- Handle offline mode gracefully (cached token reuse, helpful errors).  
- Provide verbose logging around token acquisition (without dumping secrets).  
- Support non-interactive mode (env vars) for CI pipelines.  
- Align CLI exit codes with backend problem types (401 -> exit 10, etc.).

## Deliverables
- Updated CLI project + tests.  
- Docs/help updates referencing Authority integration.  
- Sample command snippets for operators (login, job trigger with scope).  
- Changelog entry describing auth changes.

## Coordination
- Collaborate with Auth Libraries team to stabilize client API.  
- Sync with Feedser integration to ensure required scopes align.  
- Provide feedback to Authority Core on error payloads for better CLI UX.  
- Work with Docs team for documentation rollout.