docs: document multi-org sessions and fix token file layout#525
Merged
platinummonkey merged 3 commits intoMay 23, 2026
Merged
Conversation
Adds upstream-accurate docs for pup's named-session model (`--org`, `DD_ORG`, `--subdomain`, `--org-uuid`, `pup auth list`) and the site-selection rules that let `--org <name>` recall the correct site without re-passing `DD_SITE` on every command. Also corrects two specific inaccuracies in the existing docs: 1. Token file layout. The current docs claim named sessions are stored in `tokens_<site>_<org>.json`. The actual implementation (`src/auth/storage.rs`) uses one `tokens_<site>.json` per site with org name as an inner map key. The same applies to the keychain backend (one entry per site, org-keyed payload). 2. Storage default on platforms with a keychain. The README's Token Storage paragraph already mentioned keychain, but the file-structure block in `docs/OAUTH2.md` only showed `~/.config/pup/`. Clarified that `tokens_<site>.json` only exists when no keychain is available or `DD_TOKEN_STORAGE=file` is set. Examples use real public DD_SITE values (datadoghq.com, datadoghq.eu, us3/us5/ap1/ap2.datadoghq.com, ddog-gov.com) rather than placeholders. Verified against source (`config.rs:find_session_site`, `auth/storage.rs:FileStorage`) and empirically with `pup auth status --org <name>` and `pup logs query --org <name>` without `DD_SITE` set.
Three iterations of code-reviewer (Claude) + Codex review against the pup source surfaced these issues, all now fixed: - `--site` is only on `pup auth login` and `pup auth status`, not a global flag. Removed `pup monitors list --site ...` and dropped `--site` from the "Site selection rules" list in both files; added a clarifying sentence about which two subcommands accept it. - `client_<site>.json` is not "always file-based". On secure-store platforms, client credentials live alongside tokens in the per-site store entry (SiteData struct). Rewrote File Structure trailer in docs/OAUTH2.md. - Token Storage paragraphs were inaccurate per-platform. macOS uses Apple's Security framework (Touch ID), not the `keyring` crate. Windows shards large per-site blobs across multiple WinCred records. Rewrote both files' Token Storage descriptions. - `pup auth logout` has no `--site` flag — added a `DD_SITE=` example and an explicit note. - Default-session logout deletes the shared per-site DCR client credentials, which breaks refresh for any named-org session on the same site. Added a "Side effect on sibling sessions" callout in docs/OAUTH2.md and a matching note in README.md. - File-mode storage layout had separate `tokens_<site>.json` and `client_<site>.json` files, but the new wording implied one entry. Clarified the secure-store-vs-file distinction in both files. - `~/.config/pup/config.yaml` `site:` field was missing from the site precedence list. Added. - "Disambiguation" wording for default (unnamed) sessions implied there was some ambiguity to resolve. Rewrote to reflect that unnamed sessions are simply not addressable via `--org`. Also reframed the DD_SITE list as "Common values" rather than "Valid values" so it doesn't read as exhaustive (omitting datad0g.com is intentional — staging is internal-only, but the CLI does accept it). Added a "Recommended pattern" callout in the Multi-Org Support section suggesting that users working with multiple orgs give every session an explicit `--org` name rather than mixing the default slot with named sessions — both because the default slot is easy to re-log into different orgs by accident, and because logging out the default tears down the shared DCR client credentials.
Second pass through /review-fix-loop (3 iterations, converged) caught
a few residual issues that the first pass missed:
- README "Login to a non-default site" example previously implied that
any subsequent command would recall the site from the session.
Recall only happens when the command itself carries --org / DD_ORG.
Made the parenthetical explicit.
- README + OAUTH2 logout side-effect note previously said sibling
named sessions must be re-logged-in to recover. Actually any
subsequent `pup auth login` on that site (default or named)
re-registers the shared DCR client credentials, after which the
other sessions can refresh normally.
- OAUTH2 Multi-Site "Each site maintains separate" bullets mixed
file-mode filenames with mode-agnostic wording. Rewrote both bullets
mode-agnostically and pointed at the Token Storage section.
- `pup auth list` description differed between README and OAUTH2
(README listed three fields, OAUTH2 listed four). Aligned both to
the full set: site, org, org_uuid, scopes, expiry, status.
- Windows WinCred sharding was described as conditional ("when blob
exceeds size limit") in three places. Per the source, chunking is
unconditional: every save produces a count record plus one or more
chunk records. Rewrote all three locations.
platinummonkey
approved these changes
May 23, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents the named-session multi-org model (
--org,DD_ORG,--subdomain,--org-uuid,pup auth list) and the site-selection rules that let--org <name>recall the correct site without re-passingDD_SITEon every subcommand. Also corrects two inaccuracies in the existing docs.What changed
Doc fixes (existing claims that don't match the code):
docs/OAUTH2.md(Token Storage, File Structure sections) claim named sessions go totokens_<site>_<org>.json. The actual implementation insrc/auth/storage.rs(FileStorage::save_tokens) writes onetokens_<site>.jsonper site, containing anOrgTokenMapkeyed by org name. The keychain backend mirrors that (one entry per site, org-keyed payload).~/.config/pup/tokens_datadoghq_com.json. On platforms with a keychain that file does not exist by default. Clarified that the JSON files are only used when no keychain is available orDD_TOKEN_STORAGE=fileis set.New content:
### Multiple sites and orgsblock in README's OAuth2 section with worked examples.## Multi-Org Supportsection indocs/OAUTH2.mdcovering: logging into multiple orgs, using a named session, inspecting/managing sessions, site selection rules, and the session registry file.--siteflag form alongsideDD_SITEand to cover all public Datadog sites (datadoghq.com, datadoghq.eu, us3/us5/ap1/ap2.datadoghq.com, ddog-gov.com).### 1. Loginand### 4. Logoutextended with named-session examples and cross-links.Verification
src/config.rs(site precedence,find_session_sitelookup),src/auth/storage.rs(file/keychain backends, session registry,SessionEntrystruct),src/auth/dcr.rs(subdomain handling at login only),src/main.rs(Auth command help,--org-uuidsemantics).pup auth status --org <name>andpup logs query --org <name> --query "*" --limit 1resolve the correct site from the session registry with noDD_SITEenv var set.Follow-up (not in this PR)
The in-binary help for the
authcommand (rendered from doc comments atsrc/main.rs:560-568) has the sametokens_<site>_<org>.jsonclaim and a TOKEN STORAGE block that omits the keychain default. Worth a follow-up to align it with the README and OAUTH2.md, but kept out of this PR to keep the review surface focused on user-facing docs.(from Claude Code)