From fdf03929133cc6ce1ee8f387420efbccae8d312e Mon Sep 17 00:00:00 2001 From: Dan Dunning <2349188+dunningdan@users.noreply.github.com> Date: Mon, 20 Jul 2026 10:04:18 -0400 Subject: [PATCH 1/8] =?UTF-8?q?=F0=9F=93=9D=20Add=20pixee-o11y=20skill=20f?= =?UTF-8?q?or=20observability=20auth?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a coding-agent skill covering `pixee o11y login/token/status/logout` — the device-flow authentication to a Pixee deployment's observability stack and the per-user bearer tokens used to query VictoriaMetrics/Logs/Traces over HTTP. Distinct from `pixee-auth` (the REST API token). Also lists it in the README. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_016Y4oU4W5LfteyHBVQZLGM5 --- README.md | 3 + skills/pixee-o11y/SKILL.md | 130 +++++++++++++++++++++++++++++++++++++ 2 files changed, 133 insertions(+) create mode 100644 skills/pixee-o11y/SKILL.md diff --git a/README.md b/README.md index af1b131..39b9b44 100644 --- a/README.md +++ b/README.md @@ -118,6 +118,9 @@ individual skills directly with `npx skills add pixee/pixee-cli --skill `: Prerequisite for the others. - [`pixee-auth`](./skills/pixee-auth/SKILL.md) — login, status, credential precedence, and fixing exit-code-2 failures. +- [`pixee-o11y`](./skills/pixee-o11y/SKILL.md) — `pixee o11y login/token/status/logout`: + device-flow auth to a deployment's observability stack and per-user bearer tokens for + querying VictoriaMetrics/Logs/Traces. - [`pixee-api`](./skills/pixee-api/SKILL.md) — the `pixee api` escape hatch and HAL discovery. - [`pixee-preferences`](./skills/pixee-preferences/SKILL.md) — read and write Pixee organization preferences from files or stdin. diff --git a/skills/pixee-o11y/SKILL.md b/skills/pixee-o11y/SKILL.md new file mode 100644 index 0000000..fc6729d --- /dev/null +++ b/skills/pixee-o11y/SKILL.md @@ -0,0 +1,130 @@ +--- +name: pixee-o11y +description: "Authenticate to a Pixee deployment's observability stack via the OAuth2 device flow and mint per-user bearer tokens to query VictoriaMetrics, VictoriaLogs, and VictoriaTraces over HTTP." +metadata: + version: 1.0.0 + openclaw: + category: "developer-tools" + requires: + bins: + - pixee + cliHelp: "pixee o11y --help" +--- + +# pixee o11y + +> **PREREQUISITE:** Read `../pixee-shared/SKILL.md` for global flags, exit codes, +> and error handling. + +`pixee o11y` authenticates you to a Pixee deployment's **observability stack** +(VictoriaMetrics, VictoriaLogs, VictoriaTraces, served under `/o11y/` behind the +deployment's identity provider) and mints a short-lived, **per-user** bearer +token you can send to those HTTP APIs. + +This is a **separate credential** from `pixee auth` (see `../pixee-auth/SKILL.md`): +`pixee auth` stores the Pixee REST API token used by every other subcommand; +`pixee o11y` obtains an OAuth token from the deployment's identity provider for +the observability endpoints. The two do not interchange — the REST API token is +rejected by the observability proxy, and vice versa. `pixee o11y` reuses only the +**server** resolution (`--server` → `PIXEE_SERVER` → stored config); an explicit +`[server]` positional argument overrides it. + +## Commands + +### pixee o11y login + +Run the OAuth2 device-authorization flow against the deployment's identity +provider. Prints a verification URL (and opens your browser unless +`--no-browser`), waits for you to approve, then caches the access and refresh +tokens locally with `0600` permissions. Tokens are stored per-server, so you can +be logged in to several deployments at once. + +```bash +# Uses the configured server (from `pixee auth login` or PIXEE_SERVER) +pixee o11y login + +# Or target a specific deployment (URL or bare host) +pixee o11y login https://pixee.example.com +pixee o11y login edge.getpixee.com + +# Headless / SSH: print the URL instead of trying to open a browser +pixee o11y login pixee.example.com --no-browser +``` + +### pixee o11y token + +Print a currently-valid bearer token, refreshing it silently if it has expired. +Designed for scripts and coding agents — feed it straight into `curl`: + +```bash +TOKEN=$(pixee o11y token https://pixee.example.com) + +# Logs — VictoriaLogs / LogsQL +curl -sG -H "Authorization: Bearer $TOKEN" \ + https://pixee.example.com/o11y/logs/select/logsql/query \ + --data-urlencode 'query=_time:1h | limit 100' + +# Metrics — VictoriaMetrics / PromQL +curl -sG -H "Authorization: Bearer $TOKEN" \ + https://pixee.example.com/o11y/metrics/prometheus/api/v1/query \ + --data-urlencode 'query=up' + +# Traces — VictoriaTraces / Jaeger API +curl -s -H "Authorization: Bearer $TOKEN" \ + https://pixee.example.com/o11y/traces/select/jaeger/api/services +``` + +If no session is stored (or it expired and cannot be refreshed), `token` exits +non-zero with a message directing you to run `pixee o11y login`. + +### pixee o11y status + +Show the stored session for a server: identity, token validity, and whether a +refresh token is present. Read-only; never refreshes. Always exits 0, so it is a +safe "am I logged in?" probe. Add `--json` for machine-readable output. + +```bash +pixee o11y status https://pixee.example.com +# Server: https://pixee.example.com +# Identity: dan.dunning@pixee.ai +# Token: valid (expires in 58m) +# Refresh token: present +``` + +### pixee o11y logout + +Remove the stored observability credentials for a server (local only; does not +revoke the token server-side). + +```bash +pixee o11y logout https://pixee.example.com +``` + +## Typical workflow + +```bash +pixee o11y login pixee.example.com # once, opens the browser +TOKEN=$(pixee o11y token pixee.example.com) # any time, refreshes as needed +curl -sG -H "Authorization: Bearer $TOKEN" \ + https://pixee.example.com/o11y/logs/select/logsql/query \ + --data-urlencode 'query=_time:15m level="ERROR" | limit 50' +``` + +## Notes + +- **Per-user identity.** The token carries your identity from the deployment's + IdP, so observability access is governed by your existing IdP policies and + actions are attributable to you — there is no shared key. +- **Availability.** Programmatic observability access requires the observability + stack (and its `pixee-cli` provider) to be enabled on the deployment. If + `login` reports it cannot discover the endpoints, that deployment isn't set up + for it yet. +- **Query languages** are the backends' native ones — LogsQL (VictoriaLogs), + PromQL/MetricsQL (VictoriaMetrics), and the Jaeger query API (VictoriaTraces); + `pixee o11y` handles only authentication, not query composition. + +## See also + +- `../pixee-auth/SKILL.md` — the Pixee REST API token used by every other + subcommand (distinct from the observability token here). +- `../pixee-shared/SKILL.md` — global flags, exit codes, and TLS trust. From c231c4e3eeafb60bb9df7655620e17c3dfb3fb76 Mon Sep 17 00:00:00 2001 From: Dan Dunning <2349188+dunningdan@users.noreply.github.com> Date: Mon, 27 Jul 2026 13:26:15 -0400 Subject: [PATCH 2/8] =?UTF-8?q?=F0=9F=93=9D=20Merge=20the=20device-flow=20?= =?UTF-8?q?skill=20into=20`pixee-auth`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The CLI collapsed `pixee o11y *` into `pixee auth *` (pixee-cli-private#37) because the device-flow token is not observability-only — the same credential authorizes the platform REST API. This repo had the same duplication one layer up: a `pixee-o11y` skill alongside the existing `pixee-auth` skill, for what is now a single command group. Gilday suggested renaming `skills/pixee-o11y` -> `skills/pixee-auth`, but that directory already exists and documents the API-key credential. Renaming would have collided; merging is the coherent version of the same instruction. - Fold the device-flow content into `skills/pixee-auth/SKILL.md`: a table contrasting the two credentials (per-user OAuth vs the deployment's shared API key) and when to reach for each, the four subcommands, and the fact that the device flow needs no browser on the CLI's own host — so it works over SSH. - Delete `skills/pixee-o11y/`. - Drop the claim that the two credentials "do not interchange". Since the Authentik provider was generalized (pixee-enterprise-server#3940) the device-flow token is accepted by the REST API too, so that framing is stale. - Correct the credential-resolution list: it omitted the global `--token` flag, which does override PIXEE_TOKEN and stored config for every subcommand (see src/index.ts in pixee-cli-private) — the skill claimed it applied only to `auth login`. - Bump the skill to 1.1.0 and rewrite the README entry. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01BH3r86Ky1Z8gBVAR3yEsw4 --- README.md | 8 +- skills/pixee-auth/SKILL.md | 174 ++++++++++++++++++++++++++++--------- skills/pixee-o11y/SKILL.md | 130 --------------------------- 3 files changed, 135 insertions(+), 177 deletions(-) delete mode 100644 skills/pixee-o11y/SKILL.md diff --git a/README.md b/README.md index 39b9b44..126b863 100644 --- a/README.md +++ b/README.md @@ -116,11 +116,9 @@ individual skills directly with `npx skills add pixee/pixee-cli --skill `: - [`pixee-shared`](./skills/pixee-shared/SKILL.md) — global flags, exit codes, error handling. Prerequisite for the others. -- [`pixee-auth`](./skills/pixee-auth/SKILL.md) — login, status, credential precedence, and - fixing exit-code-2 failures. -- [`pixee-o11y`](./skills/pixee-o11y/SKILL.md) — `pixee o11y login/token/status/logout`: - device-flow auth to a deployment's observability stack and per-user bearer tokens for - querying VictoriaMetrics/Logs/Traces. +- [`pixee-auth`](./skills/pixee-auth/SKILL.md) — `pixee auth login/token/status/logout`: + per-user device-flow login or the deployment's shared API key, bearer tokens for the REST API + and the observability endpoints, credential precedence, and fixing exit-code-2 failures. - [`pixee-api`](./skills/pixee-api/SKILL.md) — the `pixee api` escape hatch and HAL discovery. - [`pixee-preferences`](./skills/pixee-preferences/SKILL.md) — read and write Pixee organization preferences from files or stdin. diff --git a/skills/pixee-auth/SKILL.md b/skills/pixee-auth/SKILL.md index ae31fb0..061607f 100644 --- a/skills/pixee-auth/SKILL.md +++ b/skills/pixee-auth/SKILL.md @@ -1,8 +1,8 @@ --- name: pixee-auth -description: "Store and validate Pixee API tokens and inspect the current authentication state." +description: "Authenticate to a Pixee deployment — the per-user OAuth2 device flow or the deployment's shared API key — mint bearer tokens for the REST API and observability endpoints, and inspect the current authentication state." metadata: - version: 1.0.0 + version: 1.1.0 openclaw: category: "developer-tools" requires: @@ -16,77 +16,167 @@ metadata: > **PREREQUISITE:** Read `../pixee-shared/SKILL.md` for global flags, exit codes, and error > handling. Exit code 2 is the signal that authentication failed — this skill is the fix. -`pixee auth` manages the credentials `pixee` uses to talk to a Pixee deployment: it stores an API -token, configures which server to target, validates, and surfaces the current authentication -state. +`pixee auth` manages the credentials `pixee` uses to talk to a Pixee deployment. Two kinds exist, +and picking the right one matters: + +| | Device flow (default) | Shared API key (`--token`) | +| --- | --- | --- | +| Issued by | the deployment's identity provider, per user | the KOTS admin console, one per deployment | +| Identity | you, by name — attributable | none; a shared `api-token` principal | +| Lifetime | short-lived, refreshes silently | static until an operator rotates it | +| Revoking one person | revoke them in the IdP | impossible without rotating for everyone | +| Reaches `/o11y/` endpoints | yes | no | +| Works unattended | no — one interactive approval | yes | + +Prefer the device flow whenever a human is present. Use the API key for CI and unattended +automation, where no one can approve a browser prompt. + +The two are stored separately, so adopting the device flow never disturbs an existing API-key +setup. ## Commands ### pixee auth login -Store and validate a Pixee API token. The token is written to a platform-appropriate config file -(`~/Library/Preferences/pixee` on macOS, `$XDG_CONFIG_HOME/pixee` on Linux, -`%APPDATA%\pixee\Config` on Windows) with `0600` permissions on Unix (Windows inherits the -per-user directory's NTFS ACL). `pixee auth login` confirms the token against -`GET /api/v1/users/me` — success exits 0, invalid token exits 2. +With no `--token`, runs the OAuth2 device-authorization flow (RFC 8628) against the deployment's +identity provider. Prints a verification URL (and opens your browser unless `--no-browser`), waits +for you to approve, then caches the access and refresh tokens with `0600` permissions. Tokens are +stored per-server, so you can be logged in to several deployments at once. + +```bash +# Device flow against the configured server +pixee auth login + +# Or target a specific deployment (URL or bare host) +pixee auth login https://pixee.example.com +pixee auth login edge.getpixee.com + +# Headless / SSH: print the URL instead of trying to open a browser +pixee auth login pixee.example.com --no-browser +``` + +Because the device flow needs no redirect back to the CLI, **the browser does not have to be on +the machine running `pixee`.** You can log in over SSH and approve the printed URL from your +laptop — as long as that device can reach the deployment's URL. + +With `--token`, stores and validates the deployment's shared Pixee API key instead, confirming it +against `GET /api/v1/users/me`. Success exits 0; an invalid key exits 2. + +```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 - + +# Bare --token prompts interactively +pixee auth login --server https://pixee.example.com --token +``` Flags: -- `--server ` — deployment to authenticate against. Required on first login. -- `--token ` — API token from the admin console's **API Tokens** page. -- `--token -` — read the token from stdin. Prefer this over `--token `: flag arguments land - in shell history. +- `--server ` — deployment to authenticate against. +- `--token [value]` — use the shared API key instead of the device flow. Bare `--token` prompts; + `--token -` reads stdin; `--token ` takes it inline (lands in shell history). +- `--no-browser` — device flow only: print the verification URL, don't try to open a browser. + +### pixee auth token + +Print a currently-valid device-flow bearer token, refreshing it silently if it has expired. +Designed for scripts and coding agents — feed it straight into `curl`: ```bash -# Interactive login -pixee auth login --server https://pixee.example.com --token pixee_xxx +TOKEN=$(pixee auth token https://pixee.example.com) -# Stdin form — keeps the token off the command line -echo -n "$PIXEE_TOKEN" | pixee auth login --server https://pixee.example.com --token - +# Pixee REST API +curl -s -H "Authorization: Bearer $TOKEN" https://pixee.example.com/api/v1/users/me + +# Logs — VictoriaLogs / LogsQL +curl -sG -H "Authorization: Bearer $TOKEN" \ + https://pixee.example.com/o11y/logs/select/logsql/query \ + --data-urlencode 'query=_time:1h | limit 100' + +# Metrics — VictoriaMetrics / PromQL +curl -sG -H "Authorization: Bearer $TOKEN" \ + https://pixee.example.com/o11y/metrics/prometheus/api/v1/query \ + --data-urlencode 'query=up' + +# Traces — VictoriaTraces / Jaeger API +curl -s -H "Authorization: Bearer $TOKEN" \ + https://pixee.example.com/o11y/traces/select/jaeger/api/services ``` +If no session is stored (or it expired and cannot be refreshed), `token` exits non-zero with a +message directing you to run `pixee auth login`. It never prints the shared API key — callers that +configured one already hold it. + ### pixee auth status -Print the current authentication state: configured server, whether the stored token validates, and -the authenticated identity. API-token auth surfaces a generic `api-token` identity rather than a -real user's name or email — the device-code flow (future) provides real identity. +Print the current authentication state: the configured server, whether the stored API key +validates, and the per-user session's identity and expiry. Read-only; never refreshes. Always +exits 0, so it is a safe "am I logged in?" probe. Add `--json` for machine-readable output. ```bash pixee auth status -# Logged in to https://pixee.example.com as api-token -# Token: valid +# Server: https://pixee.example.com +# Token: stored (valid) +# Identity: api-token +# Session: dan.dunning@pixee.ai +# Session token: valid (expires in 58m) +# Refresh token: present +``` + +### pixee auth logout + +Remove the stored per-user credentials for a server. Local only — it does not revoke the token +server-side, and it deliberately leaves the shared API key in place, since that is deployment +configuration rather than a personal session. + +```bash +pixee auth logout https://pixee.example.com ``` ## Credential resolution -For every subcommand except `pixee auth login`, token and server are resolved in order: +For every subcommand except `pixee auth login`: -- **Token:** `PIXEE_TOKEN` env var → stored config. -- **Server:** `--server` flag → `PIXEE_SERVER` env var → stored config. +- **Token:** `--token` flag → `PIXEE_TOKEN` env var → stored credentials. +- **Server:** `--server` flag → `PIXEE_SERVER` env var → stored config. A `[server]` positional + argument on the `auth` subcommands overrides all of it. Setting `PIXEE_TOKEN` + `PIXEE_SERVER` is the CI/CD and agent-automation path — no -`pixee auth login` step is required. The `--token` flag exists only on `pixee auth login` itself -(to *store* a token); it is not a per-invocation override for other subcommands. +`pixee auth login` step required, and unaffected by anything the device flow does. -There is no hardcoded default server. If no server is configured via any mechanism, commands exit -with an error directing the user to run `pixee auth login` or set `PIXEE_SERVER`. +There is no hardcoded default server. If none is configured, commands exit with an error directing +the user to run `pixee auth login` or set `PIXEE_SERVER`. ## Fixing exit code 2 When a command exits with code 2 ("Authentication failed"): -1. Run `pixee auth status` to check which server is configured and whether the current token - validates. -2. If the server is wrong, re-run `pixee auth login --server ` or set - `PIXEE_SERVER`. -3. If the token is expired or revoked, generate a new one in the admin console's **API Tokens** - page and log in again — preferably via `--token -` stdin or the `PIXEE_TOKEN` env var. +1. Run `pixee auth status` to see which server is configured and which credentials are live. +2. If the server is wrong, re-run `pixee auth login --server ` or set `PIXEE_SERVER`. +3. If a per-user session expired and cannot refresh, run `pixee auth login` again. +4. If the shared API key is invalid, rotate it in the admin console and log in again — preferably + via `--token -` stdin or the `PIXEE_TOKEN` env var. + +## Notes + +- **Per-user identity.** A device-flow token carries your identity from the deployment's IdP, so + access is governed by your existing IdP policies and actions are attributable to you. The shared + API key surfaces a generic `api-token` identity instead. +- **Availability.** The device flow requires the deployment's `pixee-cli` identity-provider client + to be present. If `login` reports it cannot discover the endpoints, that deployment isn't set up + for it yet — fall back to `--token`. +- **Query languages** for the observability endpoints are the backends' native ones — LogsQL + (VictoriaLogs), PromQL/MetricsQL (VictoriaMetrics), and the Jaeger query API (VictoriaTraces). + `pixee auth` handles only authentication, not query composition. ## Best practices -- Generate a separate API token per automation context so tokens can be rotated or revoked - independently. -- Prefer `PIXEE_TOKEN` / `PIXEE_SERVER` env vars for CI/CD and agent automation — no local state, - nothing to commit. -- Use `pixee auth status` to confirm the configured server matches the deployment where the token - was issued; mismatched server is the most common cause of 401s. +- Prefer the device flow for interactive work so actions are attributable to a person. +- Reserve the shared API key for CI/CD, and prefer `PIXEE_TOKEN` / `PIXEE_SERVER` env vars there — + no local state, nothing to commit. +- Use `pixee auth status` to confirm the configured server matches the deployment the credential + came from; a mismatched server is the most common cause of 401s. + +## See also + +- `../pixee-shared/SKILL.md` — global flags, exit codes, and TLS trust. diff --git a/skills/pixee-o11y/SKILL.md b/skills/pixee-o11y/SKILL.md deleted file mode 100644 index fc6729d..0000000 --- a/skills/pixee-o11y/SKILL.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -name: pixee-o11y -description: "Authenticate to a Pixee deployment's observability stack via the OAuth2 device flow and mint per-user bearer tokens to query VictoriaMetrics, VictoriaLogs, and VictoriaTraces over HTTP." -metadata: - version: 1.0.0 - openclaw: - category: "developer-tools" - requires: - bins: - - pixee - cliHelp: "pixee o11y --help" ---- - -# pixee o11y - -> **PREREQUISITE:** Read `../pixee-shared/SKILL.md` for global flags, exit codes, -> and error handling. - -`pixee o11y` authenticates you to a Pixee deployment's **observability stack** -(VictoriaMetrics, VictoriaLogs, VictoriaTraces, served under `/o11y/` behind the -deployment's identity provider) and mints a short-lived, **per-user** bearer -token you can send to those HTTP APIs. - -This is a **separate credential** from `pixee auth` (see `../pixee-auth/SKILL.md`): -`pixee auth` stores the Pixee REST API token used by every other subcommand; -`pixee o11y` obtains an OAuth token from the deployment's identity provider for -the observability endpoints. The two do not interchange — the REST API token is -rejected by the observability proxy, and vice versa. `pixee o11y` reuses only the -**server** resolution (`--server` → `PIXEE_SERVER` → stored config); an explicit -`[server]` positional argument overrides it. - -## Commands - -### pixee o11y login - -Run the OAuth2 device-authorization flow against the deployment's identity -provider. Prints a verification URL (and opens your browser unless -`--no-browser`), waits for you to approve, then caches the access and refresh -tokens locally with `0600` permissions. Tokens are stored per-server, so you can -be logged in to several deployments at once. - -```bash -# Uses the configured server (from `pixee auth login` or PIXEE_SERVER) -pixee o11y login - -# Or target a specific deployment (URL or bare host) -pixee o11y login https://pixee.example.com -pixee o11y login edge.getpixee.com - -# Headless / SSH: print the URL instead of trying to open a browser -pixee o11y login pixee.example.com --no-browser -``` - -### pixee o11y token - -Print a currently-valid bearer token, refreshing it silently if it has expired. -Designed for scripts and coding agents — feed it straight into `curl`: - -```bash -TOKEN=$(pixee o11y token https://pixee.example.com) - -# Logs — VictoriaLogs / LogsQL -curl -sG -H "Authorization: Bearer $TOKEN" \ - https://pixee.example.com/o11y/logs/select/logsql/query \ - --data-urlencode 'query=_time:1h | limit 100' - -# Metrics — VictoriaMetrics / PromQL -curl -sG -H "Authorization: Bearer $TOKEN" \ - https://pixee.example.com/o11y/metrics/prometheus/api/v1/query \ - --data-urlencode 'query=up' - -# Traces — VictoriaTraces / Jaeger API -curl -s -H "Authorization: Bearer $TOKEN" \ - https://pixee.example.com/o11y/traces/select/jaeger/api/services -``` - -If no session is stored (or it expired and cannot be refreshed), `token` exits -non-zero with a message directing you to run `pixee o11y login`. - -### pixee o11y status - -Show the stored session for a server: identity, token validity, and whether a -refresh token is present. Read-only; never refreshes. Always exits 0, so it is a -safe "am I logged in?" probe. Add `--json` for machine-readable output. - -```bash -pixee o11y status https://pixee.example.com -# Server: https://pixee.example.com -# Identity: dan.dunning@pixee.ai -# Token: valid (expires in 58m) -# Refresh token: present -``` - -### pixee o11y logout - -Remove the stored observability credentials for a server (local only; does not -revoke the token server-side). - -```bash -pixee o11y logout https://pixee.example.com -``` - -## Typical workflow - -```bash -pixee o11y login pixee.example.com # once, opens the browser -TOKEN=$(pixee o11y token pixee.example.com) # any time, refreshes as needed -curl -sG -H "Authorization: Bearer $TOKEN" \ - https://pixee.example.com/o11y/logs/select/logsql/query \ - --data-urlencode 'query=_time:15m level="ERROR" | limit 50' -``` - -## Notes - -- **Per-user identity.** The token carries your identity from the deployment's - IdP, so observability access is governed by your existing IdP policies and - actions are attributable to you — there is no shared key. -- **Availability.** Programmatic observability access requires the observability - stack (and its `pixee-cli` provider) to be enabled on the deployment. If - `login` reports it cannot discover the endpoints, that deployment isn't set up - for it yet. -- **Query languages** are the backends' native ones — LogsQL (VictoriaLogs), - PromQL/MetricsQL (VictoriaMetrics), and the Jaeger query API (VictoriaTraces); - `pixee o11y` handles only authentication, not query composition. - -## See also - -- `../pixee-auth/SKILL.md` — the Pixee REST API token used by every other - subcommand (distinct from the observability token here). -- `../pixee-shared/SKILL.md` — global flags, exit codes, and TLS trust. From ddc7469d0fdc03952209fb0c50dd886d650a8544 Mon Sep 17 00:00:00 2001 From: Dan Dunning <2349188+dunningdan@users.noreply.github.com> Date: Tue, 28 Jul 2026 23:42:27 -0400 Subject: [PATCH 3/8] =?UTF-8?q?=F0=9F=93=9D=20Document=20`--server`=20inst?= =?UTF-8?q?ead=20of=20a=20positional=20deployment?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The CLI unified the auth group on `--server` (pixee-cli-private#37): `auth` was the only command group where a positional argument named a deployment rather than the object of the verb. Update every example, and correct the credential-resolution section, which described the positional as overriding everything else. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01BH3r86Ky1Z8gBVAR3yEsw4 --- skills/pixee-auth/SKILL.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/skills/pixee-auth/SKILL.md b/skills/pixee-auth/SKILL.md index 061607f..415b41b 100644 --- a/skills/pixee-auth/SKILL.md +++ b/skills/pixee-auth/SKILL.md @@ -48,11 +48,11 @@ stored per-server, so you can be logged in to several deployments at once. pixee auth login # Or target a specific deployment (URL or bare host) -pixee auth login https://pixee.example.com -pixee auth login edge.getpixee.com +pixee auth login --server https://pixee.example.com +pixee auth login --server edge.getpixee.com # Headless / SSH: print the URL instead of trying to open a browser -pixee auth login pixee.example.com --no-browser +pixee auth login --server pixee.example.com --no-browser ``` Because the device flow needs no redirect back to the CLI, **the browser does not have to be on @@ -72,7 +72,9 @@ pixee auth login --server https://pixee.example.com --token Flags: -- `--server ` — deployment to authenticate against. +- `--server ` — deployment to authenticate against. Every `auth` subcommand takes it; the + global `--server` and `PIXEE_SERVER` work too, and after a successful login the server is + remembered so later commands need no flag. - `--token [value]` — use the shared API key instead of the device flow. Bare `--token` prompts; `--token -` reads stdin; `--token ` takes it inline (lands in shell history). - `--no-browser` — device flow only: print the verification URL, don't try to open a browser. @@ -83,7 +85,7 @@ Print a currently-valid device-flow bearer token, refreshing it silently if it h Designed for scripts and coding agents — feed it straight into `curl`: ```bash -TOKEN=$(pixee auth token https://pixee.example.com) +TOKEN=$(pixee auth token --server https://pixee.example.com) # Pixee REST API curl -s -H "Authorization: Bearer $TOKEN" https://pixee.example.com/api/v1/users/me @@ -130,7 +132,7 @@ server-side, and it deliberately leaves the shared API key in place, since that configuration rather than a personal session. ```bash -pixee auth logout https://pixee.example.com +pixee auth logout --server https://pixee.example.com ``` ## Credential resolution @@ -138,8 +140,8 @@ pixee auth logout https://pixee.example.com For every subcommand except `pixee auth login`: - **Token:** `--token` flag → `PIXEE_TOKEN` env var → stored credentials. -- **Server:** `--server` flag → `PIXEE_SERVER` env var → stored config. A `[server]` positional - argument on the `auth` subcommands overrides all of it. +- **Server:** `--server` flag → `PIXEE_SERVER` env var → stored config. A subcommand-level + `--server` (available on every `auth` subcommand) takes precedence over the global one. Setting `PIXEE_TOKEN` + `PIXEE_SERVER` is the CI/CD and agent-automation path — no `pixee auth login` step required, and unaffected by anything the device flow does. From 5714f8c921c20d1c87099cc4f2d8122c868d2585 Mon Sep 17 00:00:00 2001 From: Dan Dunning <2349188+dunningdan@users.noreply.github.com> Date: Wed, 29 Jul 2026 14:59:43 -0400 Subject: [PATCH 4/8] =?UTF-8?q?=F0=9F=93=9D=20Document=20`auth=20token`'s?= =?UTF-8?q?=20required=20--server=20and=20the=20session=20listing?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follows pixee-cli-private#37: - `auth token` now always requires `--server`. The skill previously said the server is remembered "so later commands need no flag", which is now wrong for exactly the command where getting it wrong matters most: `token` returns a bare credential and the caller picks the URL, so a defaulted server could hand one deployment's token to a request against another. - `auth status` lists every server you hold a session for, expired ones included, and collapses to a single line when nothing is configured. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01BH3r86Ky1Z8gBVAR3yEsw4 --- skills/pixee-auth/SKILL.md | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/skills/pixee-auth/SKILL.md b/skills/pixee-auth/SKILL.md index 415b41b..8d39834 100644 --- a/skills/pixee-auth/SKILL.md +++ b/skills/pixee-auth/SKILL.md @@ -72,9 +72,9 @@ pixee auth login --server https://pixee.example.com --token Flags: -- `--server ` — deployment to authenticate against. Every `auth` subcommand takes it; the - global `--server` and `PIXEE_SERVER` work too, and after a successful login the server is - remembered so later commands need no flag. +- `--server ` — deployment to authenticate against. The global `--server` and `PIXEE_SERVER` + work too, and after a successful login the server is remembered, so `status` and `logout` need no + flag. **`auth token` is the exception — it always requires `--server`** (see below). - `--token [value]` — use the shared API key instead of the device flow. Bare `--token` prompts; `--token -` reads stdin; `--token ` takes it inline (lands in shell history). - `--no-browser` — device flow only: print the verification URL, don't try to open a browser. @@ -84,6 +84,13 @@ Flags: Print a currently-valid device-flow bearer token, refreshing it silently if it has expired. Designed for scripts and coding agents — feed it straight into `curl`: +**`--server` is required here**, unlike every other command. Everywhere else the server and the +credential are resolved together and used together, so they cannot disagree. This command returns a +bare token and *you* choose the URL, so a defaulted server would let you pipe one deployment's +credential into a request against another — silently, with neither half able to detect it. +`PIXEE_SERVER` and the stored default are deliberately not honored. Run `pixee auth status` to see +which servers you have sessions for. + ```bash TOKEN=$(pixee auth token --server https://pixee.example.com) @@ -112,8 +119,9 @@ configured one already hold it. ### pixee auth status Print the current authentication state: the configured server, whether the stored API key -validates, and the per-user session's identity and expiry. Read-only; never refreshes. Always -exits 0, so it is a safe "am I logged in?" probe. Add `--json` for machine-readable output. +validates, the per-user session's identity and expiry, and **every other server you hold a session +for**. Read-only; never refreshes. Always exits 0, so it is a safe "am I logged in?" probe. Add +`--json` for machine-readable output. ```bash pixee auth status @@ -123,8 +131,15 @@ pixee auth status # Session: dan.dunning@pixee.ai # Session token: valid (expires in 58m) # Refresh token: present +# +# Other sessions: +# https://edge.example.com expired (will refresh on next use) ``` +Expired sessions are listed too — they are the ones you cannot otherwise see, and this is where you +find out what to pass `auth token --server`. With nothing configured at all it collapses to one +line rather than repeating "not configured" for each credential. + ### pixee auth logout Remove the stored per-user credentials for a server. Local only — it does not revoke the token From 82a99d4d89bffa54f9cc71c6cdd661109461d6a1 Mon Sep 17 00:00:00 2001 From: Dan Dunning <2349188+dunningdan@users.noreply.github.com> Date: Wed, 29 Jul 2026 22:09:27 -0400 Subject: [PATCH 5/8] =?UTF-8?q?=F0=9F=93=9D=20Document=20`auth=20use`,=20t?= =?UTF-8?q?he=20cross-deployment=20note,=20and=20lead=20with=20device=20fl?= =?UTF-8?q?ow?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README's getting-started told new users to authenticate with the shared API key, passed inline: pixee auth login --server https://pixee.example.com --token That is the least attributable credential by the least safe method — inline values land in shell history, which the skill itself warns about. It now leads with `pixee auth login`, which identifies the person, and presents the shared key as the unattended path via `--token -` on stdin. Skill (1.1.0 -> 1.2.0): - Documents `pixee auth use `, which was shipped undocumented. - Documents the stderr note `auth token` prints when the named server is not the one `auth use` points at, and that stdout stays exactly one token so piping is unaffected. - Credential resolution now names `auth use` as how the stored default is set, rather than describing it as something that just happens. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01BH3r86Ky1Z8gBVAR3yEsw4 --- README.md | 20 +++++++++++++++++--- skills/pixee-auth/SKILL.md | 37 +++++++++++++++++++++++++++++++++---- 2 files changed, 50 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 126b863..50f2fb6 100644 --- a/README.md +++ b/README.md @@ -48,8 +48,8 @@ shasum -a 256 --ignore-missing -c SHA256SUMS ## Getting started ```bash -# Authenticate against a Pixee deployment -pixee auth login --server https://pixee.example.com --token +# Log in as yourself — opens your browser to sign in through your identity provider +pixee auth login --server https://pixee.example.com # Send an authenticated request to any Pixee REST API endpoint pixee api /api/v1/repositories --paginate @@ -58,6 +58,20 @@ pixee api /api/v1/repositories --paginate pixee workflow list --repo my-repo ``` +Logging in this way gives you a short-lived token that identifies **you**, so your +actions are attributable and your permissions come from your identity provider. + +For CI and other unattended contexts, where nobody can approve a browser prompt, +use your deployment's shared API key instead — read it from stdin rather than +passing it inline, so it stays out of your shell history: + +```bash +echo -n "$PIXEE_TOKEN" | pixee auth login --server https://pixee.example.com --token - +``` + +Working with more than one deployment? `pixee auth use ` sets the one +later commands target, and `pixee auth status` shows every session you hold. + Run `pixee --help` to see every subcommand. ## TLS configuration @@ -116,7 +130,7 @@ individual skills directly with `npx skills add pixee/pixee-cli --skill `: - [`pixee-shared`](./skills/pixee-shared/SKILL.md) — global flags, exit codes, error handling. Prerequisite for the others. -- [`pixee-auth`](./skills/pixee-auth/SKILL.md) — `pixee auth login/token/status/logout`: +- [`pixee-auth`](./skills/pixee-auth/SKILL.md) — `pixee auth login/use/token/status/logout`: per-user device-flow login or the deployment's shared API key, bearer tokens for the REST API and the observability endpoints, credential precedence, and fixing exit-code-2 failures. - [`pixee-api`](./skills/pixee-api/SKILL.md) — the `pixee api` escape hatch and HAL discovery. diff --git a/skills/pixee-auth/SKILL.md b/skills/pixee-auth/SKILL.md index 8d39834..d241016 100644 --- a/skills/pixee-auth/SKILL.md +++ b/skills/pixee-auth/SKILL.md @@ -1,8 +1,8 @@ --- name: pixee-auth -description: "Authenticate to a Pixee deployment — the per-user OAuth2 device flow or the deployment's shared API key — mint bearer tokens for the REST API and observability endpoints, and inspect the current authentication state." +description: "Authenticate to a Pixee deployment — the per-user OAuth2 device flow or the deployment's shared API key — choose which deployment commands target, mint bearer tokens for the REST API and observability endpoints, and inspect the current authentication state." metadata: - version: 1.1.0 + version: 1.2.0 openclaw: category: "developer-tools" requires: @@ -79,6 +79,24 @@ Flags: `--token -` reads stdin; `--token ` takes it inline (lands in shell history). - `--no-browser` — device flow only: print the verification URL, don't try to open a browser. +### pixee auth use + +Set the deployment that later commands target when no `--server` and no `PIXEE_SERVER` are given. + +```bash +pixee auth use ddunning.getpixee.com +# Now using https://ddunning.getpixee.com. +``` + +That default also gets set by a successful `auth login`, but only as a side effect of whichever +login happened last. `auth use` makes it deliberate — the same idea as `kubectl config use-context`. +Only the server changes: device-flow sessions live in their own per-server files and any shared API +key in the config is preserved, so switching deployments never logs you out or clears a key that CI +depends on. + +It does not require an existing session, so you can point at a deployment before logging in to it; +it says so on stderr rather than failing. + ### pixee auth token Print a currently-valid device-flow bearer token, refreshing it silently if it has expired. @@ -112,6 +130,17 @@ curl -s -H "Authorization: Bearer $TOKEN" \ https://pixee.example.com/o11y/traces/select/jaeger/api/services ``` +When the server you name is not the one `auth use` currently points at, `token` says so on +**stderr** — a note, not a warning, since wanting another environment's token is routine: + +```bash +$ pixee auth token --server edge.getpixee.com +note: token for https://edge.getpixee.com; 'pixee auth use' currently points at https://ddunning.getpixee.com +eyJhbGciOi… +``` + +stdout stays exactly one token, so `$(pixee auth token --server …)` and `2>/dev/null` both behave. + If no session is stored (or it expired and cannot be refreshed), `token` exits non-zero with a message directing you to run `pixee auth login`. It never prints the shared API key — callers that configured one already hold it. @@ -155,8 +184,8 @@ pixee auth logout --server https://pixee.example.com For every subcommand except `pixee auth login`: - **Token:** `--token` flag → `PIXEE_TOKEN` env var → stored credentials. -- **Server:** `--server` flag → `PIXEE_SERVER` env var → stored config. A subcommand-level - `--server` (available on every `auth` subcommand) takes precedence over the global one. +- **Server:** `--server` flag → `PIXEE_SERVER` env var → stored config (set by `auth use`, or by a + successful `auth login`). A subcommand-level `--server` takes precedence over the global one. Setting `PIXEE_TOKEN` + `PIXEE_SERVER` is the CI/CD and agent-automation path — no `pixee auth login` step required, and unaffected by anything the device flow does. From f59583f042c9a6e6da9cb6b51856a51cd1096681 Mon Sep 17 00:00:00 2001 From: Dan Dunning <2349188+dunningdan@users.noreply.github.com> Date: Thu, 30 Jul 2026 16:39:01 -0400 Subject: [PATCH 6/8] =?UTF-8?q?=F0=9F=93=9D=20Document=20the=20exit-2=20co?= =?UTF-8?q?ntract,=20the=20split-pairing=20401,=20and=20the=20--json=20sha?= =?UTF-8?q?pe?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Catches up with two behaviours added to the CLI after the last skill commit (pixee-cli-private#37). - **Exit 2 is now uniform.** Device-flow auth failures previously exited 1 while API-key failures exited 2; both are 2 now, so an agent can branch on it without knowing which credential is in play. Said explicitly, since the whole point of the code change was to make that contract dependable. - **The confusing 401.** `server` and `token` in the config are a pair, and a device login repoints the server without touching a stored API key — so commands outside the `auth` group can send one deployment's key to another. `auth status` looks healthy while everything else 401s, which is a dead end for anyone following the old four steps. Added as step 5 with the fix, and noting that `auth login` warns on stderr when it creates the situation. - **`--json` fields named** (`configured`, `apiKey`, `sessions[]` with `server`, `isDefault`, `identity`, `tokenValid`, `canRefresh`, `expiresAt`), with a nudge to read `sessions[]` rather than parse the prose lines — agents were otherwise left to infer the shape. Skill 1.2.0 -> 1.3.0. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01BH3r86Ky1Z8gBVAR3yEsw4 --- skills/pixee-auth/SKILL.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/skills/pixee-auth/SKILL.md b/skills/pixee-auth/SKILL.md index d241016..992895f 100644 --- a/skills/pixee-auth/SKILL.md +++ b/skills/pixee-auth/SKILL.md @@ -2,7 +2,7 @@ name: pixee-auth description: "Authenticate to a Pixee deployment — the per-user OAuth2 device flow or the deployment's shared API key — choose which deployment commands target, mint bearer tokens for the REST API and observability endpoints, and inspect the current authentication state." metadata: - version: 1.2.0 + version: 1.3.0 openclaw: category: "developer-tools" requires: @@ -149,8 +149,12 @@ configured one already hold it. Print the current authentication state: the configured server, whether the stored API key validates, the per-user session's identity and expiry, and **every other server you hold a session -for**. Read-only; never refreshes. Always exits 0, so it is a safe "am I logged in?" probe. Add -`--json` for machine-readable output. +for**. Read-only; never refreshes. Always exits 0, so it is a safe "am I logged in?" probe. + +`--json` is the machine-readable form: `configured` (whether any credential is set at all), +`apiKey` (the rendered report lines), and `sessions[]` with `server`, `isDefault`, `identity`, +`tokenValid`, `canRefresh`, and `expiresAt` per stored session. Prefer `sessions[]` over parsing the +text output. ```bash pixee auth status @@ -195,6 +199,9 @@ the user to run `pixee auth login` or set `PIXEE_SERVER`. ## Fixing exit code 2 +Both credential types exit 2 on an authentication failure, so you can branch on it uniformly — a +missing or expired device session and an invalid API key are the same exit code. + When a command exits with code 2 ("Authentication failed"): 1. Run `pixee auth status` to see which server is configured and which credentials are live. @@ -202,6 +209,12 @@ When a command exits with code 2 ("Authentication failed"): 3. If a per-user session expired and cannot refresh, run `pixee auth login` again. 4. If the shared API key is invalid, rotate it in the admin console and log in again — preferably via `--token -` stdin or the `PIXEE_TOKEN` env var. +5. **If `auth status` looks healthy but other commands still 401**, check whether the stored API key + belongs to a *different* deployment than the current server. `server` and `token` in the config + are a pair, and a device login repoints the server without touching the key — so commands outside + the `auth` group can end up sending one deployment's key to another. `auth login` prints a note on + stderr when it creates that situation. Fix it by storing a key for this deployment + (`pixee auth login --server --token -`) or by unsetting the old one. ## Notes From ba7918137725f260897a3f74d8a7906fd76ab9fc Mon Sep 17 00:00:00 2001 From: Dan Dunning <2349188+dunningdan@users.noreply.github.com> Date: Fri, 31 Jul 2026 14:55:01 -0400 Subject: [PATCH 7/8] =?UTF-8?q?=F0=9F=93=9D=20Correct=20the=20credential?= =?UTF-8?q?=20precedence=20now=20that=20commands=20prefer=20the=20session?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit pixee/pixee-cli-private#37 grew past what this skill described. Ordinary commands no longer resolve `PIXEE_TOKEN` → stored key; they prefer the device session, so the documented precedence omitted the credential most commands actually send. - Token precedence is `--token` → device session → `PIXEE_TOKEN` → stored key. An API key outranks the session ONLY when passed explicitly on the invocation; an exported `PIXEE_TOKEN` does not, because it cannot be distinguished from a shell-profile `export`. - Dropped "unaffected by anything the device flow does". True for CI, which has no session on disk, and false on a workstation that has both — the case the reader is most likely to hit. - After `auth login`, an interactive user needs no API key at all. - `auth status` gains a `Commands will use:` line, prints only the credentials that exist, and relabels `Token:`/`Identity:` to `API key:`/`API key identity:`. Its `--json` `apiKey` is now a structured object plus a `credentialInUse` field, not rendered prose. - The split-pairing 401 is narrower: it needs no session for the current server, since otherwise the session is used instead of the mismatched key. Co-Authored-By: Claude Opus 5 (1M context) --- skills/pixee-auth/SKILL.md | 65 +++++++++++++++++++++++++++----------- 1 file changed, 47 insertions(+), 18 deletions(-) diff --git a/skills/pixee-auth/SKILL.md b/skills/pixee-auth/SKILL.md index 992895f..12f406f 100644 --- a/skills/pixee-auth/SKILL.md +++ b/skills/pixee-auth/SKILL.md @@ -28,11 +28,13 @@ and picking the right one matters: | Reaches `/o11y/` endpoints | yes | no | | Works unattended | no — one interactive approval | yes | -Prefer the device flow whenever a human is present. Use the API key for CI and unattended -automation, where no one can approve a browser prompt. +Prefer the device flow whenever a human is present. Ordinary commands (`repo list`, `scan list`, +`api`, …) use the session automatically once you have logged in, so an interactive user needs no +API key at all. Reserve the key for CI and unattended automation, where no one can approve a +browser prompt. The two are stored separately, so adopting the device flow never disturbs an existing API-key -setup. +setup — an existing key stays on disk and keeps working as the fallback. ## Commands @@ -152,18 +154,24 @@ validates, the per-user session's identity and expiry, and **every other server for**. Read-only; never refreshes. Always exits 0, so it is a safe "am I logged in?" probe. `--json` is the machine-readable form: `configured` (whether any credential is set at all), -`apiKey` (the rendered report lines), and `sessions[]` with `server`, `isDefault`, `identity`, -`tokenValid`, `canRefresh`, and `expiresAt` per stored session. Prefer `sessions[]` over parsing the -text output. +`apiKey` (a structured object: `server`, `serverSource`, `tokenSource`, `tokenValid`, `identity`, +`reachable`), `credentialInUse` (`"session"`, `"api-key"`, or `null`), and `sessions[]` with +`server`, `isDefault`, `identity`, `tokenValid`, `canRefresh`, and `expiresAt` per stored session. +Prefer these over parsing the text output. + +Only the credentials that exist are printed: with no API key configured the `API key` lines are +omitted, and vice versa. Both appear when both are present, which is the case where the pairing +matters. ```bash pixee auth status # Server: https://pixee.example.com -# Token: stored (valid) -# Identity: api-token +# API key: stored (valid) +# API key identity: api-token # Session: dan.dunning@pixee.ai # Session token: valid (expires in 58m) # Refresh token: present +# Commands will use: your session # # Other sessions: # https://edge.example.com expired (will refresh on next use) @@ -187,12 +195,27 @@ pixee auth logout --server https://pixee.example.com For every subcommand except `pixee auth login`: -- **Token:** `--token` flag → `PIXEE_TOKEN` env var → stored credentials. +- **Token:** `--token` flag → **device session for that server** → `PIXEE_TOKEN` env var → stored + API key. - **Server:** `--server` flag → `PIXEE_SERVER` env var → stored config (set by `auth use`, or by a successful `auth login`). A subcommand-level `--server` takes precedence over the global one. -Setting `PIXEE_TOKEN` + `PIXEE_SERVER` is the CI/CD and agent-automation path — no -`pixee auth login` step required, and unaffected by anything the device flow does. +The device session outranks both the env var and the stored key, so once you have logged in, +ordinary commands are already running as you. **An API key beats the session only when handed to +the CLI explicitly with `--token` on that invocation.** `PIXEE_TOKEN` sits below the session on +purpose: an env var is indistinguishable from an `export` in a shell profile, so treating it as a +deliberate choice meant anyone with one exported would log in, see a live session, and still have +every command quietly send the shared key. + +Setting `PIXEE_TOKEN` + `PIXEE_SERVER` remains the CI/CD and agent-automation path — no +`pixee auth login` step required. CI is unaffected in practice because a runner has no session on +disk. On a workstation that has both, the session wins; use `--token` to force the key. + +If you are unsure which credential is in play, `pixee auth status` states it outright: + +``` +Commands will use: your session +``` There is no hardcoded default server. If none is configured, commands exit with an error directing the user to run `pixee auth login` or set `PIXEE_SERVER`. @@ -209,12 +232,15 @@ When a command exits with code 2 ("Authentication failed"): 3. If a per-user session expired and cannot refresh, run `pixee auth login` again. 4. If the shared API key is invalid, rotate it in the admin console and log in again — preferably via `--token -` stdin or the `PIXEE_TOKEN` env var. -5. **If `auth status` looks healthy but other commands still 401**, check whether the stored API key - belongs to a *different* deployment than the current server. `server` and `token` in the config - are a pair, and a device login repoints the server without touching the key — so commands outside - the `auth` group can end up sending one deployment's key to another. `auth login` prints a note on - stderr when it creates that situation. Fix it by storing a key for this deployment - (`pixee auth login --server --token -`) or by unsetting the old one. +5. **If `auth status` looks healthy but other commands still 401**, read its + `Commands will use:` line — it names the credential those commands actually send, which is not + always the one you were looking at. The usual cause is a stored API key belonging to a + *different* deployment than the current server: `server` and `token` in the config are a pair, + and a device login repoints the server without touching the key. With no session for the current + server, commands fall back to that mismatched key and 401. `auth login` prints a note on stderr + when it creates that situation. Fix it by logging in to this deployment + (`pixee auth login --server `), storing a key for it + (`pixee auth login --server --token -`), or unsetting the old one. ## Notes @@ -230,9 +256,12 @@ When a command exits with code 2 ("Authentication failed"): ## Best practices -- Prefer the device flow for interactive work so actions are attributable to a person. +- Prefer the device flow for interactive work so actions are attributable to a person. After + `auth login`, ordinary commands use it with no further configuration. - Reserve the shared API key for CI/CD, and prefer `PIXEE_TOKEN` / `PIXEE_SERVER` env vars there — no local state, nothing to commit. +- To force the API key on a machine that also has a session, pass `--token` explicitly; exporting + `PIXEE_TOKEN` will not override the session. - Use `pixee auth status` to confirm the configured server matches the deployment the credential came from; a mismatched server is the most common cause of 401s. From 6e1dc9dc2bf643111b11654b4df31a70ce30e323 Mon Sep 17 00:00:00 2001 From: Dan Dunning <2349188+dunningdan@users.noreply.github.com> Date: Fri, 31 Jul 2026 22:04:51 -0400 Subject: [PATCH 8/8] =?UTF-8?q?=F0=9F=93=9D=20Drop=20em=20dashes=20from=20?= =?UTF-8?q?the=20auth=20skill=20prose?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Punctuation only, on the lines this branch introduced: colons, semicolons, commas, or full stops in place of em dashes. No guidance changes. Pre-existing em dashes on untouched lines are left alone. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 6 ++-- skills/pixee-auth/SKILL.md | 56 +++++++++++++++++++------------------- 2 files changed, 31 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 50f2fb6..1d3011a 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ shasum -a 256 --ignore-missing -c SHA256SUMS ## Getting started ```bash -# Log in as yourself — opens your browser to sign in through your identity provider +# Log in as yourself; opens your browser to sign in through your identity provider pixee auth login --server https://pixee.example.com # Send an authenticated request to any Pixee REST API endpoint @@ -62,7 +62,7 @@ Logging in this way gives you a short-lived token that identifies **you**, so yo actions are attributable and your permissions come from your identity provider. For CI and other unattended contexts, where nobody can approve a browser prompt, -use your deployment's shared API key instead — read it from stdin rather than +use your deployment's shared API key instead. Read it from stdin rather than passing it inline, so it stays out of your shell history: ```bash @@ -130,7 +130,7 @@ individual skills directly with `npx skills add pixee/pixee-cli --skill `: - [`pixee-shared`](./skills/pixee-shared/SKILL.md) — global flags, exit codes, error handling. Prerequisite for the others. -- [`pixee-auth`](./skills/pixee-auth/SKILL.md) — `pixee auth login/use/token/status/logout`: +- [`pixee-auth`](./skills/pixee-auth/SKILL.md): `pixee auth login/use/token/status/logout`, per-user device-flow login or the deployment's shared API key, bearer tokens for the REST API and the observability endpoints, credential precedence, and fixing exit-code-2 failures. - [`pixee-api`](./skills/pixee-api/SKILL.md) — the `pixee api` escape hatch and HAL discovery. diff --git a/skills/pixee-auth/SKILL.md b/skills/pixee-auth/SKILL.md index 12f406f..61a629a 100644 --- a/skills/pixee-auth/SKILL.md +++ b/skills/pixee-auth/SKILL.md @@ -1,6 +1,6 @@ --- name: pixee-auth -description: "Authenticate to a Pixee deployment — the per-user OAuth2 device flow or the deployment's shared API key — choose which deployment commands target, mint bearer tokens for the REST API and observability endpoints, and inspect the current authentication state." +description: "Authenticate to a Pixee deployment using the per-user OAuth2 device flow or the deployment's shared API key, choose which deployment commands target, mint bearer tokens for the REST API and observability endpoints, and inspect the current authentication state." metadata: version: 1.3.0 openclaw: @@ -22,11 +22,11 @@ and picking the right one matters: | | Device flow (default) | Shared API key (`--token`) | | --- | --- | --- | | Issued by | the deployment's identity provider, per user | the KOTS admin console, one per deployment | -| Identity | you, by name — attributable | none; a shared `api-token` principal | +| Identity | you, by name; attributable | none; a shared `api-token` principal | | Lifetime | short-lived, refreshes silently | static until an operator rotates it | | Revoking one person | revoke them in the IdP | impossible without rotating for everyone | | Reaches `/o11y/` endpoints | yes | no | -| Works unattended | no — one interactive approval | yes | +| Works unattended | no; one interactive approval | yes | Prefer the device flow whenever a human is present. Ordinary commands (`repo list`, `scan list`, `api`, …) use the session automatically once you have logged in, so an interactive user needs no @@ -34,7 +34,7 @@ API key at all. Reserve the key for CI and unattended automation, where no one c browser prompt. The two are stored separately, so adopting the device flow never disturbs an existing API-key -setup — an existing key stays on disk and keeps working as the fallback. +setup; an existing key stays on disk and keeps working as the fallback. ## Commands @@ -59,13 +59,13 @@ pixee auth login --server pixee.example.com --no-browser Because the device flow needs no redirect back to the CLI, **the browser does not have to be on the machine running `pixee`.** You can log in over SSH and approve the printed URL from your -laptop — as long as that device can reach the deployment's URL. +laptop, as long as that device can reach the deployment's URL. With `--token`, stores and validates the deployment's shared Pixee API key instead, confirming it against `GET /api/v1/users/me`. Success exits 0; an invalid key exits 2. ```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 - # Bare --token prompts interactively @@ -74,12 +74,12 @@ pixee auth login --server https://pixee.example.com --token Flags: -- `--server ` — deployment to authenticate against. The global `--server` and `PIXEE_SERVER` +- `--server `: deployment to authenticate against. The global `--server` and `PIXEE_SERVER` work too, and after a successful login the server is remembered, so `status` and `logout` need no - flag. **`auth token` is the exception — it always requires `--server`** (see below). -- `--token [value]` — use the shared API key instead of the device flow. Bare `--token` prompts; + flag. **`auth token` is the exception; it always requires `--server`** (see below). +- `--token [value]`: use the shared API key instead of the device flow. Bare `--token` prompts; `--token -` reads stdin; `--token ` takes it inline (lands in shell history). -- `--no-browser` — device flow only: print the verification URL, don't try to open a browser. +- `--no-browser`: device flow only. Print the verification URL, don't try to open a browser. ### pixee auth use @@ -91,7 +91,7 @@ pixee auth use ddunning.getpixee.com ``` That default also gets set by a successful `auth login`, but only as a side effect of whichever -login happened last. `auth use` makes it deliberate — the same idea as `kubectl config use-context`. +login happened last. `auth use` makes it deliberate, the same idea as `kubectl config use-context`. Only the server changes: device-flow sessions live in their own per-server files and any shared API key in the config is preserved, so switching deployments never logs you out or clears a key that CI depends on. @@ -102,12 +102,12 @@ it says so on stderr rather than failing. ### pixee auth token Print a currently-valid device-flow bearer token, refreshing it silently if it has expired. -Designed for scripts and coding agents — feed it straight into `curl`: +Designed for scripts and coding agents. Feed it straight into `curl`: **`--server` is required here**, unlike every other command. Everywhere else the server and the credential are resolved together and used together, so they cannot disagree. This command returns a bare token and *you* choose the URL, so a defaulted server would let you pipe one deployment's -credential into a request against another — silently, with neither half able to detect it. +credential into a request against another, silently, with neither half able to detect it. `PIXEE_SERVER` and the stored default are deliberately not honored. Run `pixee auth status` to see which servers you have sessions for. @@ -117,23 +117,23 @@ TOKEN=$(pixee auth token --server https://pixee.example.com) # Pixee REST API curl -s -H "Authorization: Bearer $TOKEN" https://pixee.example.com/api/v1/users/me -# Logs — VictoriaLogs / LogsQL +# Logs: VictoriaLogs / LogsQL curl -sG -H "Authorization: Bearer $TOKEN" \ https://pixee.example.com/o11y/logs/select/logsql/query \ --data-urlencode 'query=_time:1h | limit 100' -# Metrics — VictoriaMetrics / PromQL +# Metrics: VictoriaMetrics / PromQL curl -sG -H "Authorization: Bearer $TOKEN" \ https://pixee.example.com/o11y/metrics/prometheus/api/v1/query \ --data-urlencode 'query=up' -# Traces — VictoriaTraces / Jaeger API +# Traces: VictoriaTraces / Jaeger API curl -s -H "Authorization: Bearer $TOKEN" \ https://pixee.example.com/o11y/traces/select/jaeger/api/services ``` When the server you name is not the one `auth use` currently points at, `token` says so on -**stderr** — a note, not a warning, since wanting another environment's token is routine: +**stderr**, a note rather than a warning, since wanting another environment's token is routine: ```bash $ pixee auth token --server edge.getpixee.com @@ -144,7 +144,7 @@ eyJhbGciOi… stdout stays exactly one token, so `$(pixee auth token --server …)` and `2>/dev/null` both behave. If no session is stored (or it expired and cannot be refreshed), `token` exits non-zero with a -message directing you to run `pixee auth login`. It never prints the shared API key — callers that +message directing you to run `pixee auth login`. It never prints the shared API key; callers that configured one already hold it. ### pixee auth status @@ -177,13 +177,13 @@ pixee auth status # https://edge.example.com expired (will refresh on next use) ``` -Expired sessions are listed too — they are the ones you cannot otherwise see, and this is where you +Expired sessions are listed too. They are the ones you cannot otherwise see, and this is where you find out what to pass `auth token --server`. With nothing configured at all it collapses to one line rather than repeating "not configured" for each credential. ### pixee auth logout -Remove the stored per-user credentials for a server. Local only — it does not revoke the token +Remove the stored per-user credentials for a server. Local only; it does not revoke the token server-side, and it deliberately leaves the shared API key in place, since that is deployment configuration rather than a personal session. @@ -207,7 +207,7 @@ purpose: an env var is indistinguishable from an `export` in a shell profile, so deliberate choice meant anyone with one exported would log in, see a live session, and still have every command quietly send the shared key. -Setting `PIXEE_TOKEN` + `PIXEE_SERVER` remains the CI/CD and agent-automation path — no +Setting `PIXEE_TOKEN` + `PIXEE_SERVER` remains the CI/CD and agent-automation path, with no `pixee auth login` step required. CI is unaffected in practice because a runner has no session on disk. On a workstation that has both, the session wins; use `--token` to force the key. @@ -222,7 +222,7 @@ the user to run `pixee auth login` or set `PIXEE_SERVER`. ## Fixing exit code 2 -Both credential types exit 2 on an authentication failure, so you can branch on it uniformly — a +Both credential types exit 2 on an authentication failure, so you can branch on it uniformly. A missing or expired device session and an invalid API key are the same exit code. When a command exits with code 2 ("Authentication failed"): @@ -230,10 +230,10 @@ When a command exits with code 2 ("Authentication failed"): 1. Run `pixee auth status` to see which server is configured and which credentials are live. 2. If the server is wrong, re-run `pixee auth login --server ` or set `PIXEE_SERVER`. 3. If a per-user session expired and cannot refresh, run `pixee auth login` again. -4. If the shared API key is invalid, rotate it in the admin console and log in again — preferably +4. If the shared API key is invalid, rotate it in the admin console and log in again, preferably via `--token -` stdin or the `PIXEE_TOKEN` env var. 5. **If `auth status` looks healthy but other commands still 401**, read its - `Commands will use:` line — it names the credential those commands actually send, which is not + `Commands will use:` line. It names the credential those commands actually send, which is not always the one you were looking at. The usual cause is a stored API key belonging to a *different* deployment than the current server: `server` and `token` in the config are a pair, and a device login repoints the server without touching the key. With no session for the current @@ -249,8 +249,8 @@ When a command exits with code 2 ("Authentication failed"): API key surfaces a generic `api-token` identity instead. - **Availability.** The device flow requires the deployment's `pixee-cli` identity-provider client to be present. If `login` reports it cannot discover the endpoints, that deployment isn't set up - for it yet — fall back to `--token`. -- **Query languages** for the observability endpoints are the backends' native ones — LogsQL + for it yet; fall back to `--token`. +- **Query languages** for the observability endpoints are the backends' native ones: LogsQL (VictoriaLogs), PromQL/MetricsQL (VictoriaMetrics), and the Jaeger query API (VictoriaTraces). `pixee auth` handles only authentication, not query composition. @@ -258,7 +258,7 @@ When a command exits with code 2 ("Authentication failed"): - Prefer the device flow for interactive work so actions are attributable to a person. After `auth login`, ordinary commands use it with no further configuration. -- Reserve the shared API key for CI/CD, and prefer `PIXEE_TOKEN` / `PIXEE_SERVER` env vars there — +- Reserve the shared API key for CI/CD, and prefer `PIXEE_TOKEN` / `PIXEE_SERVER` env vars there: no local state, nothing to commit. - To force the API key on a machine that also has a session, pass `--token` explicitly; exporting `PIXEE_TOKEN` will not override the session. @@ -267,4 +267,4 @@ When a command exits with code 2 ("Authentication failed"): ## See also -- `../pixee-shared/SKILL.md` — global flags, exit codes, and TLS trust. +- `../pixee-shared/SKILL.md`: global flags, exit codes, and TLS trust.