From 1d259e2f1c81274c810a888efd5f570e16cfb6e7 Mon Sep 17 00:00:00 2001 From: Dan Dunning <2349188+dunningdan@users.noreply.github.com> Date: Fri, 31 Jul 2026 16:20:15 -0400 Subject: [PATCH 1/3] =?UTF-8?q?=F0=9F=93=9D=20Document=20signing=20in=20as?= =?UTF-8?q?=20yourself,=20now=20the=20CLI's=20default=20credential?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The page described the shared API key as the only way to authenticate. The CLI now signs users in through their deployment's identity provider by default, and ordinary commands use that session, so the documented flow was both the harder path and no longer the one most readers want. - Leads with signing in as yourself: no admin-console token needed, actions attributable to a person, and the browser need not be on the machine running `pixee` — which matters for SSH sessions. - Keeps the shared API key documented for CI and unattended use, where nobody can approve a prompt. - Corrects credential resolution. It read `PIXEE_TOKEN` -> stored config, which omitted the session entirely; it is now `--token` -> session -> `PIXEE_TOKEN` -> stored key, with the note that only an explicit `--token` outranks the session. CI is unchanged: a runner has no session, so it uses the key. - Refreshes the `pixee auth status` example, which quoted output from two revisions ago, and adds the `auth` subcommands to Common Commands — the group had no entry there at all. - Notes that a permission change reaches the CLI at the next refresh, within one token lifetime. The removal direction is the one worth knowing. Co-Authored-By: Claude Opus 5 (1M context) --- docs/api/cli.md | 82 ++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 64 insertions(+), 18 deletions(-) diff --git a/docs/api/cli.md b/docs/api/cli.md index a7a9077..f7c2fdd 100644 --- a/docs/api/cli.md +++ b/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 — 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) — including 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 ` | 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 ` | Choose which deployment subsequent commands target. | +| `pixee auth token --server ` | Print a currently-valid bearer for use with `curl` or a coding agent. Requires an explicit server. | +| `pixee auth logout --server ` | Remove the locally stored session for a deployment. | | `pixee repo list` | List repositories registered with the platform. Filter with `--name `. | | `pixee scan list --repo ` | List scans for a repository. Filter with `--branch`, `--tool`, `--analysis-state`, `--has-analysis`. | | `pixee scan get ` | 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. From 8008f50c5c7dde38a7c864b64842d68ec7f792cc Mon Sep 17 00:00:00 2001 From: Dan Dunning <2349188+dunningdan@users.noreply.github.com> Date: Fri, 31 Jul 2026 21:38:21 -0400 Subject: [PATCH 2/3] =?UTF-8?q?=F0=9F=93=9D=20Stop=20the=20CI/CD=20runbook?= =?UTF-8?q?=20recommending=20an=20interactive=20login?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The exit-code-2 step said to "reset both with `pixee auth login`". A bare `auth login` now starts a browser sign-in, which cannot complete on a build runner — the one place this page's readers are. Point at the pipeline credentials instead (`PIXEE_TOKEN` / `PIXEE_SERVER`, or `--token -` to store a key), and say plainly why the interactive form is not an option here. Also nudges toward `auth status`'s new line naming which credential will actually be sent, since a mismatched pair is the usual cause. Co-Authored-By: Claude Opus 5 (1M context) --- docs/integrations/ci-cd.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/integrations/ci-cd.md b/docs/integrations/ci-cd.md index f854126..9011dca 100644 --- a/docs/integrations/ci-cd.md +++ b/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 --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. From b85ee706ffa8558322ae6ece231dc1969e538783 Mon Sep 17 00:00:00 2001 From: Dan Dunning <2349188+dunningdan@users.noreply.github.com> Date: Fri, 31 Jul 2026 21:45:56 -0400 Subject: [PATCH 3/3] =?UTF-8?q?=F0=9F=93=9D=20Drop=20em=20dashes=20from=20?= =?UTF-8?q?the=20CLI=20authentication=20prose?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrites the seven em dashes this branch introduced as semicolons, full stops, or plain clauses. No wording or meaning changes beyond the punctuation. Pre-existing em dashes elsewhere in the file are left alone; they are not part of this change and rewriting them would bury the substance in noise. Co-Authored-By: Claude Opus 5 (1M context) --- docs/api/cli.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/api/cli.md b/docs/api/cli.md index f7c2fdd..4bba167 100644 --- a/docs/api/cli.md +++ b/docs/api/cli.md @@ -45,10 +45,10 @@ The CLI supports two credentials. Which one you want depends on whether a person | | 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 | +| 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 | +| Works unattended | no; one interactive approval | yes | ### Sign in as yourself @@ -66,7 +66,7 @@ pixee auth login --server https://pixee.example.com 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. -Once you are signed in, ordinary commands run as you — no API key required: +Once you are signed in, ordinary commands run as you, with no API key required: ```bash pixee auth status @@ -79,14 +79,14 @@ pixee auth status 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) — including a permission being **removed**. Run `pixee auth login` again to pick it up immediately. +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. +# 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 - ``` @@ -99,9 +99,9 @@ For every subcommand except `pixee auth login`: - **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. -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. +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. +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.