Skip to content

ISS-8131: Fold device-flow auth into the pixee-auth skill - #91

Open
dunningdan wants to merge 8 commits into
mainfrom
feat/pixee-o11y-skill
Open

ISS-8131: Fold device-flow auth into the pixee-auth skill#91
dunningdan wants to merge 8 commits into
mainfrom
feat/pixee-o11y-skill

Conversation

@dunningdan

@dunningdan dunningdan commented Jul 21, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

/towards ISS-8131

Documents the CLI's new per-user device-flow authentication for coding agents, by folding it into the existing pixee-auth skill rather than shipping a second auth skill.

Why a merge and not a new skill

This PR originally added skills/pixee-o11y, on the framing that observability auth was a separate credential from pixee auth. Two things changed that:

  1. The Authentik provider was generalized (pixee/pixee-enterprise-server#3940) and the CLI collapsed pixee o11y * into pixee auth * (pixee/pixee-cli-private#37): one credential, two surfaces.
  2. Review on the helm PR suggested renaming skills/pixee-o11y → skills/pixee-auth. That directory already exists and documents the API-key credential, so a literal rename would have collided. Merging is the coherent version of the same instruction.

What the merged skill covers

  • A table contrasting the two credentials, per-user OAuth device flow vs. the deployment's shared API key, and when to reach for each (device flow whenever a human is present; API key for unattended CI, which is the only thing it can do that the device flow cannot).
  • All four subcommands: login (both paths), token, status, logout.
  • That the device flow needs no browser on the CLI's own host, so it works over SSH, with the caveat that the approving device must be able to reach the deployment's URL.
  • Bearer usage against both the REST API and the /o11y/ logs/metrics/traces endpoints.

skills/pixee-o11y/ is deleted and the README entry rewritten; the skill is bumped to 1.1.0.

Two corrections to pre-existing content

Both were already wrong in pixee-auth/SKILL.md before this PR:

  • It claimed the two credentials "do not interchange", i.e. that the REST token is rejected by the o11y proxy and vice versa. Stale since the provider was generalized: the device token is accepted by both.
  • Its credential-resolution list omitted the global --token flag, asserting it applied only to auth login. src/index.ts declares --token globally and it overrides PIXEE_TOKEN and stored config for every subcommand.

Not corrected, needs a second pair of eyes

The skill tells users to get the API key from "the admin console's API Tokens page." The PES docs (api-access.md) and kots/config.yaml both describe it as a single global system key under the KOTS admin console's Config → Basic Settings ("Enable Pixee API key"). "API Tokens page" looks wrong, but I could not rule out a separate User Platform surface, so I left the wording alone rather than guess in a public skill.

Second pass: --server, not a positional

The CLI then unified its auth group on --server and dropped the positional deployment argument (auth was the only group where a positional named a deployment rather than the object of the verb). Every call site here was updated accordingly. Left alone, the documented examples would have told readers to run a form that no longer parses. The credential-resolution section, which described the positional as overriding everything else, is corrected too.

Dependency

Merge alongside the CLI release that ships pixee auth login | token | status | logout.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BH3r86Ky1Z8gBVAR3yEsw4

@dunningdan @claude
📝 Add pixee-o11y skill for observability auth
fdf0392 
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) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016Y4oU4W5LfteyHBVQZLGM5
@dunningdan
dunningdan marked this pull request as ready for review July 21, 2026 15:21
@dunningdan @claude
📝 Merge the device-flow skill into pixee-auth
c231c4e 
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) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BH3r86Ky1Z8gBVAR3yEsw4
@dunningdan dunningdan changed the title ISS-8131: Add pixee-o11y skill for observability auth ISS-8131: Fold device-flow auth into the pixee-auth skill Jul 27, 2026
dunningdan and others added 6 commits July 28, 2026 23:42
@dunningdan @claude
📝 Document --server instead of a positional deployment
ddc7469 
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) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BH3r86Ky1Z8gBVAR3yEsw4
@dunningdan @claude
📝 Document auth token's required --server and the session listing
5714f8c 
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) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BH3r86Ky1Z8gBVAR3yEsw4
@dunningdan @claude
📝 Document auth use, the cross-deployment note, and lead with devic…
82a99d4 
…e flow

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 <your-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 <server>`, 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) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BH3r86Ky1Z8gBVAR3yEsw4
@dunningdan @claude
📝 Document the exit-2 contract, the split-pairing 401, and the --json…
f59583f 
… shape

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) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BH3r86Ky1Z8gBVAR3yEsw4
@dunningdan @claude
📝 Correct the credential precedence now that commands prefer the session
ba79181 
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) <noreply@anthropic.com>
@dunningdan @claude
📝 Drop em dashes from the auth skill prose
6e1dc9d 
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) <noreply@anthropic.com>
@sonarqubecloud

sonarqubecloud Bot commented Aug 1, 2026

Copy link
Copy Markdown

Quality Gate Passed Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@nahsra nahsra nahsra approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@dunningdan @nahsra