docs(cli): models and usage + reference with troubleshooting - #405
docs(cli): models and usage + reference with troubleshooting#405hongyi-chen wants to merge 5 commits into
Conversation
Fill in the three cli-reference pages from the Warp CLI launch skeleton: - cli/reference: command-line flags with examples, environment variables, full slash-command table (25 commands verified against the CLI command registry), and default keyboard shortcuts sourced from the CLI keybinding definitions. - cli/models-and-usage: /model picker and footer model entry, BYOK via /add-api-key + provider flags (OpenAI/Anthropic/Google), custom model routers in the picker, and cost transparency (footer credits toggle, /cost per-response summary). - cli/troubleshooting: /view-logs bundling and log locations, login troubleshooting, autoupdate behavior with /version and --version, and support links. Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR replaces placeholder CLI documentation with reference, model/usage, and troubleshooting content. The general structure is solid, but the API-key examples need safer secret-handling guidance before merge.
Concerns
- The
--api-keyexample encourages putting a Warp API key directly in the command line, where it can be captured in shell history or process listings. - The provider-key stdin example uses a plaintext
key.txtfile without warning users to avoid persistent or checked-in secret files.
Security
- Update the API-key examples to prefer
WARP_API_KEYor clearly warn about command-line exposure. - Add a caveat for stdin-based provider keys so users use a secure temporary file or secret-manager output rather than a long-lived plaintext file.
Verdict
Found: 0 critical, 1 important, 1 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| Authenticates with a Warp API key instead of the interactive browser login. Useful on hosts where a browser sign-in is inconvenient. | ||
|
|
||
| ```bash | ||
| warp --api-key YOUR_API_KEY |
There was a problem hiding this comment.
WARP_API_KEY=YOUR_API_KEY warp as the primary example, or add an explicit warning before documenting --api-key.
| The CLI prompts for the key with masked input, so the key never appears in your shell history. When stdin is piped, the key is read from stdin instead: | ||
|
|
||
| ```bash | ||
| warp --set-provider-api-key anthropic < key.txt |
There was a problem hiding this comment.
💡 [SUGGESTION] [SECURITY] The stdin example should warn users not to keep provider keys in a persistent plaintext key.txt file; suggest using a secure temporary file or piping from a secret manager and deleting any local file afterward.
Frontmatter {{WARP_CLI}} tokens are not substituted by the build (Astro's
content layer parses frontmatter outside Vite), so built titles showed the
raw token. Body prose keeps {VARS.WARP_CLI}.
Co-Authored-By: Oz <oz-agent@warp.dev>
Consolidation: the standalone troubleshooting page merges into cli/reference.mdx as a final Troubleshooting section with problem-oriented H3 subsections. Existing H2 anchors (#slash-commands, #keyboard-shortcuts) are unchanged; internal links now point at #updating and #command-line-flags. troubleshooting.mdx is restored to the base-branch stub (the orchestrator removes it at integration). Co-Authored-By: Oz <oz-agent@warp.dev>
hongyi-chen
changed the title
…cli-cli-reference
Follows the base-branch WARP_CLI var value change; body prose picks up the
new name automatically via {VARS.WARP_CLI}.
Co-Authored-By: Oz <oz-agent@warp.dev>
1 participant
Pages changed
src/content/docs/cli/reference.mdx(now includes the Troubleshooting section)src/content/docs/cli/models-and-usage.mdxsrc/content/docs/cli/troubleshooting.mdxis restored to the base-branch stub per the page consolidation (13 → 9); the orchestrator removes that page at integration.Features covered
reference
--resume,--api-key(+WARP_API_KEY),--set-provider-api-key,--clear-provider-api-key,--version,--help(verified against the CLI arg parser)WARP_API_KEY,WARP_TUI_DISABLE_AUTOUPDATE/skill-name/view-logszip bundling + macOS log location~/Library/Logs/warp-cli/; login issues (browser-less device-auth URL + code, "Login failed", wrong account via/logoutincl. web sign-out,--resumerestore failure); updating (background autoupdate applied on next launch,/version+warp --version, env/setting opt-out); getting-help links#slash-commandsand#keyboard-shortcutspreserved for sibling-page links; new#troubleshootinganchor availablemodels-and-usage
/modelpicker + footer model entry (click toggles the same picker); selection persists to the active profile's base model/add-api-key,/clear-provider-api-key+ CLI flags; providers enumerated from code (openai, anthropic, google); masked input; Auto-models-consume-credits note; cross-links to inference/BYOK docs~/.warp/custom_model_routers/definitions as the app (feature ships in default/stable flag set)/costper-response duration + credits summaryThe launch blog claims these two capabilities for the Warp Agent CLI. I verified both against warp master and could not find a shipped CLI path; eng should reconcile before launch. Neither is documented on the page:
ApiKeys.custom_endpointswere populated, but there is no CLI surface to configure an endpoint (the add/edit flow exists only in the app's settings UI), the CLI key commands accept only openai|anthropic|google (no openrouter slug), and the CLI intentionally uses a separate secure-storage namespace from the app (LaunchMode::secure_storage_service_name), so endpoints configured in the Warp app are not visible to the CLI process.If eng lands either capability (or a shared-keychain/import path) before launch, I can add them to models-and-usage with cross-links to agent-platform/inference/custom-inference-endpoint and agent-platform/inference/grok-subscription.
Dropped/unconfirmed
/add-api-keyaccept only openai|anthropic|google; xAI is excluded from the API-key provider list in code./status: dropped — no such command exists in the slash-command registry./copy-debugging-link: dropped — not in the registry; no CLI implementation found on master./fast-forward: dropped — no such slash command in the registry (auto-approve is the shipped toggle; documented under permissions page's scope)./pr-commentsdisplay: dropped — no such slash command in the registry.--list-models/ headless runs: excluded per plan — absent from the CLI arg parser.Notes for reviewers
Ctrl+Palso toggles plans in terminals without keyboard-enhancement support; I documented onlyCtrl+Shift+Pto avoid over-qualifying. Flag if you want both.Suggested reviewer(s): harry, ian (moira for custom routing)
Co-Authored-By: Oz oz-agent@warp.dev