docs(cli): document oz logout, whoami, federate, and artifact commands#59
Merged
Conversation
The missing_docs audit flagged five undocumented CLI commands. This adds coverage for the four user-facing ones (logout, whoami, federate, artifact) and marks oz harness-support as internal so it stops being flagged. * Extend reference/cli/index.mdx with `oz whoami` and `oz logout` next to the existing `oz login` section, plus pointers from "Additional commands" to the two new dedicated pages. * Add reference/cli/federate.mdx covering `oz federate issue-token`, including the supported subject-template components and AWS/GCP exchange flows. * Add reference/cli/artifacts.mdx covering `oz artifact get` and `oz artifact download`. * Wire both new pages into the CLI sidebar. * Fix the audit script for the current repo layout (Astro `src/content/docs`, `crates/warp_features`, `crates/warp_cli`) and let CLI surface-map entries use the same `internal` sentinel the API audit already supports. * Update the surface map: refresh CLI mappings to point at real `.mdx` paths and mark `oz harness-support` as internal. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
bnavetta
approved these changes
May 12, 2026
|
|
||
| # Also check OpenAPI spec | ||
| openapi_path = docs_root / "developers" / "agent-api-openapi.yaml" | ||
| # Also check OpenAPI spec (lives at repo root, not under content/docs) |
Contributor
There was a problem hiding this comment.
We should probably replace this with the warp-server version, unless it's synced from there?
| oz whoami | ||
| ``` | ||
|
|
||
| The output includes your user or service account ID, display name, email, and team (when available). For machine-readable output, set `--output-format json` or `--output-format text`. |
Contributor
There was a problem hiding this comment.
nit: we should probably start saying agent in docs rather than service account
| * **No secret rotation** - Federation removes the need to rotate static keys in environments or secrets. | ||
| * **Per-run identity** - Each run can claim a different subject (user, team, environment, skill, run ID), giving you fine-grained IAM policies. | ||
|
|
||
| For background on federation, see your cloud provider's workload identity federation guide (for example, [Google Cloud's workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation) or [AWS IAM Identity Center](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html)). |
Contributor
There was a problem hiding this comment.
We should probably link to https://docs.warp.dev/agent-platform/cloud-agents/integrations/cloud-providers/ as well here - there are streamlined paths for AWS and GCP OIDC
|
|
||
| ### Subject template components | ||
|
|
||
| The subject claim is what your cloud provider's policy will match on, so pick the combination that gives you the IAM granularity you need. Supported components: |
Contributor
There was a problem hiding this comment.
The OIDC token also includes all of these as structured claims, which is strongly preferable to squishing them all into the subject claim. We support this for providers like AWS that only handle the subject claim, and not any custom claims
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
The
missing_docsskill flagged five undocumentedozCLI commands. This PR adds first-pass reference docs for the four user-facing ones and marks the remaining hidden command as internal so it stops triggering the audit.src/content/docs/reference/cli/federate.mdx— coversoz federate issue-token(subject-template components, AWS/GCP token-exchange flows).src/content/docs/reference/cli/artifacts.mdx— coversoz artifact getandoz artifact download.src/content/docs/reference/cli/index.mdx— adds sections foroz whoamiandoz logoutnext to the existingoz logincontent, and links the two new pages from "Additional commands".src/sidebar.ts— wires the new pages into the CLI sidebar..agents/skills/missing_docs/scripts/audit_docs.py— fixes path detection so the script works against the current Astro layout (src/content/docs,crates/warp_features,crates/warp_cli) and lets CLI surface-map entries use the sameinternalsentinel that the API audit already accepts..agents/skills/missing_docs/references/feature_surface_map.md— refreshes CLI mappings to point at real.mdxfiles, adds entries for the new pages, and marksoz harness-supportas internal.After these changes the CLI category of the audit reports zero gaps.
Test plan
npm run buildsucceeds locally/reference/cli/federate/and/reference/cli/artifacts/render and the cross-links resolvepython3 .agents/skills/missing_docs/scripts/audit_docs.py --warp-internal ../warp-internal --warp-server ../warp-server --category clireports 0 gapsThis PR was created by Oz (running Claude Code).