📝 Document Signing In As Yourself In The CLI Guide

docs/api/cli.md

@@ -40,34 +40,80 @@ pixee --version
 
 ## Authenticate
 
-You need a Pixee API token (generated from the admin console's **API Tokens** page) and the URL of your Pixee deployment.
+The CLI supports two credentials. Which one you want depends on whether a person is present.
+
+|                     | Sign-in as yourself (default)                 | Shared API key (`--token`)                 |
+| ------------------- | --------------------------------------------- | ------------------------------------------ |
+| Issued by           | your deployment's identity provider, per user | the admin console's **API Tokens** page    |
+| Identity            | you, by name; actions are attributable        | none; a shared `api-token` principal       |
+| Lifetime            | short-lived, refreshes silently               | static until an operator rotates it        |
+| Revoking one person | revoke them in your IdP                       | not possible without rotating for everyone |
+| Works unattended    | no; one interactive approval                  | yes                                        |
+
+### Sign in as yourself
+
+`pixee auth login` opens your browser to sign in through your deployment's identity provider, then caches a short-lived token locally. All you need is the URL of your deployment.
 
 ```bash
-# Interactive login — stores token + server in a platform-appropriate config file.
-pixee auth login --server https://pixee.example.com --token pixee_xxx
+pixee auth login --server https://pixee.example.com
+# To authorize the Pixee CLI for https://pixee.example.com, open:
+#
+#     https://pixee.example.com/authentik/device?code=296519628
+#
+# Waiting for authorization…
+# Logged in to https://pixee.example.com as you@example.com.
+```
 
-# Stdin form — keeps the token off the command line and out of shell history.
-echo -n "$PIXEE_TOKEN" | pixee auth login --server https://pixee.example.com --token -
+The browser does not have to be on the machine running `pixee`. Because sign-in needs no redirect back to the CLI, you can log in over SSH and approve on a laptop, as long as that device can reach the deployment's URL.
 
-# Confirm.
+Once you are signed in, ordinary commands run as you, with no API key required:
+
+```bash
 pixee auth status
-# Logged in to https://pixee.example.com as api-token
-# Token: valid
+# Server: https://pixee.example.com
+# Session: you@example.com
+# Session token: valid (expires in 54m)
+# Refresh token: present
+# Commands will use: your session
+
+pixee repo list
+```
+
+The token refreshes itself, so you will not be prompted again until your session expires. Note that a change to your permissions reaches the CLI at the next refresh, within one token lifetime (up to an hour). That includes a permission being **removed**. Run `pixee auth login` again to pick it up immediately.
+
+### Shared API key
+
+Use the API key for CI and any other unattended context, where nobody can approve a browser prompt.
+
+```bash
+# Stdin form keeps the key off the command line and out of shell history.
+echo -n "$PIXEE_TOKEN" | pixee auth login --server https://pixee.example.com --token -
 ```
 
-The token is written with `0600` permissions on Unix; Windows inherits the per-user directory's NTFS ACL.
+Credentials are written with `0600` permissions on Unix; Windows inherits the per-user directory's NTFS ACL. The two are stored separately, so signing in never disturbs an existing API key.
+
+### Credential resolution
 
-**Credential resolution.** For every subcommand except `pixee auth login`, the CLI resolves credentials in this order:
+For every subcommand except `pixee auth login`:
 
-- **Token:** `PIXEE_TOKEN` env var → stored config.
+- **Token:** `--token` flag → your signed-in session for that server → `PIXEE_TOKEN` env var → stored API key.
 - **Server:** `--server` flag → `PIXEE_SERVER` env var → stored config.
 
-Setting `PIXEE_TOKEN` and `PIXEE_SERVER` is the standard CI/CD path — no `pixee auth login` step is required in pipelines.
+Your session outranks both the environment variable and the stored key, so after signing in your commands are already running as you. An API key overrides the session **only** when passed explicitly with `--token` on that invocation. An exported `PIXEE_TOKEN` does not, because it is indistinguishable from one set in a shell profile.
+
+Setting `PIXEE_TOKEN` and `PIXEE_SERVER` remains the standard CI/CD path, and no `pixee auth login` step is required in pipelines: a build runner has no session, so it uses the key. On a workstation that has both, the session wins; pass `--token` to force the key.
+
+If you are ever unsure which credential a command will send, `pixee auth status` says so on its `Commands will use:` line.
 
 ## Common Commands
 
 | Command                                                             | What It Does                                                                                         |
 | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `pixee auth login --server <url>`                                   | Sign in as yourself through your IdP. Add `--token -` to store a shared API key instead.             |
+| `pixee auth status`                                                 | Show configured credentials, every stored session, and which credential commands will use.           |
+| `pixee auth use <url>`                                              | Choose which deployment subsequent commands target.                                                  |
+| `pixee auth token --server <url>`                                   | Print a currently-valid bearer for use with `curl` or a coding agent. Requires an explicit server.   |
+| `pixee auth logout --server <url>`                                  | Remove the locally stored session for a deployment.                                                  |
 | `pixee repo list`                                                   | List repositories registered with the platform. Filter with `--name <pattern>`.                      |
 | `pixee scan list --repo <name>`                                     | List scans for a repository. Filter with `--branch`, `--tool`, `--analysis-state`, `--has-analysis`. |
 | `pixee scan get <id>`                                               | Fetch a single scan by UUID.                                                                         |
@@ -94,12 +140,12 @@ pixee repo list --json | jq '.[] | select(.type == "github") | .full_name'
 
 Scripts and agents can branch on these without parsing stderr:
 
-| Code | Meaning                                                                   |
-| ---- | ------------------------------------------------------------------------- |
-| 0    | Success                                                                   |
-| 1    | General error                                                             |
-| 2    | Authentication failure (token missing, expired, invalid, or wrong server) |
-| 3    | Resource not found                                                        |
+| Code | Meaning                                                                                    |
+| ---- | ------------------------------------------------------------------------------------------ |
+| 0    | Success                                                                                    |
+| 1    | General error                                                                              |
+| 2    | Authentication failure (not signed in, session or token expired, invalid, or wrong server) |
+| 3    | Resource not found                                                                         |
 
 Errors from the Pixee API are returned as `application/problem+json`. With `--output text`, the CLI renders the problem document in compact human-readable form; with `--output json` the raw document passes through unchanged.
 

docs/integrations/ci-cd.md

@@ -214,4 +214,4 @@ Pixee accepts scanner results through three paths:
 
 **Fix PRs not appearing.** Check that the Pixee integration has write access to the target repository. For GitHub, the App needs `pull_requests: write`. Fix generation is asynchronous — allow a few minutes after findings are ingested.
 
-**`pixee api` returns exit code 2.** Authentication failed. Run `pixee auth status` to confirm the configured server and token, or reset both with `pixee auth login`. See [Pixee CLI](/api/cli) for credential resolution rules.
+**`pixee api` returns exit code 2.** Authentication failed. Run `pixee auth status` to confirm the configured server and see which credential the CLI will send. In a pipeline, set `PIXEE_TOKEN` and `PIXEE_SERVER`, or store a key with `pixee auth login --server <url> --token -`. A bare `pixee auth login` starts an interactive browser sign-in, which cannot complete on a build runner. See [Pixee CLI](/api/cli) for credential resolution rules.