From 71b422466769b0b89e24f6c83f4b2d4369dfab18 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 30 Jun 2026 21:51:48 +0000 Subject: [PATCH] demo(missing_docs): CLI drift burn-down sample (api-key / schedule / secret) Sample output of one missing_docs drift-watch pass over the CLI backlog, to evaluate the skill's efficacy. Resolves 14 of 31 undocumented CLI commands: - Draft: document the `oz api-key list/create/expire` subcommands in the CLI reference (reference/cli/api-keys.mdx), with flags/args extracted from crates/warp_cli/src/api_key.rs. - Map (no duplication): `oz schedule *` and `oz secret *` subcommands are already documented in their feature pages, so add surface-map entries pointing there instead of re-drafting. Reviewer routing (suggest_reviewers.py): crates/warp_cli ownership -> @bnavetta, @ianhodge. Audit after: CLI findings 31 -> 17, exit 0, unaccounted none. Co-Authored-By: Oz --- .../references/feature_surface_map.md | 16 +++++++ src/content/docs/reference/cli/api-keys.mdx | 44 +++++++++++++++++++ 2 files changed, 60 insertions(+) diff --git a/.agents/skills/missing_docs/references/feature_surface_map.md b/.agents/skills/missing_docs/references/feature_surface_map.md index 45bcddd3c..d97ad5884 100644 --- a/.agents/skills/missing_docs/references/feature_surface_map.md +++ b/.agents/skills/missing_docs/references/feature_surface_map.md @@ -204,6 +204,22 @@ oz provider -> src/content/docs/reference/cli/index.mdx oz federate -> src/content/docs/reference/cli/federate.mdx oz artifact -> src/content/docs/reference/cli/artifacts.mdx oz api-key -> src/content/docs/reference/cli/api-keys.mdx + +# Scheduled-agent CLI subcommands are fully documented in the scheduled-agents feature page. +oz schedule create -> src/content/docs/platform/triggers/scheduled-agents.mdx +oz schedule list -> src/content/docs/platform/triggers/scheduled-agents.mdx +oz schedule get -> src/content/docs/platform/triggers/scheduled-agents.mdx +oz schedule update -> src/content/docs/platform/triggers/scheduled-agents.mdx +oz schedule pause -> src/content/docs/platform/triggers/scheduled-agents.mdx +oz schedule unpause -> src/content/docs/platform/triggers/scheduled-agents.mdx +oz schedule delete -> src/content/docs/platform/triggers/scheduled-agents.mdx + +# Warp-managed secret CLI subcommands are documented in the secrets feature page. +oz secret create -> src/content/docs/platform/secrets.mdx +oz secret list -> src/content/docs/platform/secrets.mdx +oz secret update -> src/content/docs/platform/secrets.mdx +oz secret delete -> src/content/docs/platform/secrets.mdx + # Internal/hidden command — not a user-facing surface, so no public docs. oz harness-support -> internal diff --git a/src/content/docs/reference/cli/api-keys.mdx b/src/content/docs/reference/cli/api-keys.mdx index 06d2b44ab..dd998e131 100644 --- a/src/content/docs/reference/cli/api-keys.mdx +++ b/src/content/docs/reference/cli/api-keys.mdx @@ -104,6 +104,50 @@ To delete an API key, find it in either the Oz web app or the Warp app's API Key Deleted keys are immediately invalidated and cannot be recovered. Any services or scripts using the deleted key will lose access and may return an [`authentication_required` error](/reference/api-and-sdk/troubleshooting/errors/authentication-required/). +## Manage API keys from the CLI + +In addition to the web and Warp app surfaces, you can manage API keys directly with the [Oz CLI](/reference/cli/). These commands are useful for scripting key rotation and for headless environments. + +### List keys + +`oz api-key list` prints your active API keys. + +* `--sort-by ` — Sort by `name`, `created-at`, `last-used-at`, `expires-at`, or `scope`. +* `--sort-order ` — Sort direction: `asc` or `desc`. +* `--jq ` — Filter the JSON output with a jq expression (for example, `--jq '.[].name'`). + +```bash +oz api-key list --sort-by last-used-at --sort-order desc +``` + +### Create a key + +`oz api-key create ` creates a key and prints the raw secret once. Store it securely — you can't retrieve it again. + +* `` — A name to identify the key (required). +* `--agent ` — Create an agent key that runs as the given cloud agent, instead of a personal key. +* One expiration choice is required: `--expires-in ` (for example, `30d`, `12h`, or `90m`), `--expires-at ` (an exact timestamp), or `--no-expiration`. +* `--jq ` — Filter the JSON output with a jq expression. + +```bash +# A personal key that expires in 30 days +oz api-key create "ci-pipeline" --expires-in 30d + +# An agent key scoped to a cloud agent, with no expiration +oz api-key create "nightly-triage" --agent AGENT_UID --no-expiration +``` + +### Expire a key + +`oz api-key expire ` immediately invalidates a key (also available as `oz api-key delete`). Expired keys can't be recovered. + +* `` — The name or UID of the key to expire (required). +* `--force` — Skip the confirmation prompt. + +```bash +oz api-key expire "ci-pipeline" --force +``` + ## Best practices * **Use personal keys for runs that should act as you.** When code changes should be attributed to your GitHub account, a personal key is the right choice. Use agent keys for automation that isn't tied to a specific user.