work

docs/modules/cli/guides/commands/auth.md

@@ -0,0 +1,19 @@
+# stella auth — Command Guide
+
+## Commands
+- `stella auth login --token <token> [--url <baseUrl>]`
+- `stella auth status`
+- `stella auth logout`
+
+## Flags
+- `--url`: API base URL; defaults to config/env.
+- `--token`: bearer token or OIDC device code (future); stored in config if allowed.
+
+## Behaviour
+- Login writes token to config file or keyring (where supported) with deterministic permissions; never echoes secrets.
+- Status prints current user/tenant scopes if available; uses exit code 3 when unauthenticated.
+- Logout removes stored token and cached session data.
+
+## Offline/air-gap notes
+- Login requires network; if `--offline` is set, command must fail with exit code 5.
+- Status/logout work offline using cached credentials only.