Wrangler — Agent Guide

Wrangler-specific context only. See root AGENTS.md for monorepo conventions.

Overview

Main CLI for Cloudflare Workers. ~2k-line yargs command tree in src/index.ts. Entry point is src/cli.ts (NOT src/index.ts).

src/cli.ts — Build entry AND library API surface (dual-purpose). Calls main() when run directly; re-exports ./api when imported as library.
src/index.ts — Yargs CLI tree builder (large file). Exports main(). NOT the package entry point despite the name.
src/api/index.ts — Public programmatic API barrel.

No console.* — use logger singleton
No __dirname / __filename — use getBasePath()
No global fetch — use undici's fetch
No direct Cloudflare REST API calls — use the Cloudflare TypeScript SDK
telemetryMessage values for UserError-compatible errors must be static, safe labels. Do not use telemetryMessage: true unless the user-facing message cannot include user input, file paths, resource names, IDs, secret names, raw API messages, or command input. Even when safe, telemetryMessage: true is usually less useful because user-facing copy is harder to group and parse than a stable telemetry label.
Format telemetryMessage values as lower-case phrases: <service or area> <command or sub-area> <failure>, for example kv namespace binding not found in config, r2 object put file not found, or pages deploy project name missing.
Keep the service/area first and the failure last so telemetry groups consistently. Prefer stable categories over user-facing copy; telemetry labels should not change just because CLI wording changes.

Pool: "forks" (not threads) — heavy global mocking
runWrangler(cmd) calls main() in-process (no subprocess)
MSW for API mocking — pre-built handlers per API domain in src/__tests__/helpers/msw/
Shared helpers: runInTempDir(), mockAccountId(), mockApiToken(), mockConfirm(), mockPrompt(), mockSelect(), captureRequestsFrom()
Unit timeout: 15s, retry: 0 (overrides shared config)
E2E timeout: 90s, bail: 1, singleThread
globals: true for vitest globals
Output normalization via normalizeString() pipeline

Test files use .test.ts (not .spec.ts)
Never import expect from vitest — use test context ({ expect }) => {}
- When adding expect as a parameter to helper functions, check ALL call sites (e.g., across deployments.test.ts, versions.test.ts)