Workers Fetch

A curl-like CLI tool for testing Cloudflare Workers locally.

Installation

Install it in your Workers project so that workers-fetch uses the same wrangler (and therefore the same workerd runtime) as your project:

npm install -D workers-fetch

wrangler is a peer dependency. If your project does not have it yet, install it too:

npm install -D wrangler

Usage

# GET request (auto-detects wrangler.json, wrangler.jsonc, or wrangler.toml)
workers-fetch

# With path
workers-fetch /api/users

# POST request
workers-fetch -X POST -H "Content-Type:application/json" -d '{"name":"test"}' /api/users

# Custom config file
workers-fetch -c wrangler.toml /api/test

# With timeout (5 seconds)
workers-fetch --timeout 5 /api/slow

Options

• [path] - Request path (default: /)
• -X, --method <method> - HTTP method (default: GET)
• -H, --header <headers...> - Custom headers (multiple allowed)
• -d, --data <data> - Request body data
• -c, --config <path> - Path to wrangler config file (auto-detected if not specified)
• --timeout <seconds> - Maximum time allowed for the request in seconds (default: 3)

Output

Returns JSON format:

{
  "status": 200,
  "statusText": "OK",
  "headers": {
    "content-type": "application/json"
  },
  "body": "{\"message\":\"success\"}"
}

Requirements

• Valid wrangler configuration file (wrangler.json, wrangler.jsonc, or wrangler.toml)
• wrangler v4.45+ as a peer dependency (use the one installed in your project)

How it works

Uses unstable_startWorker() to start a Worker locally and send requests.

AI Coding Agents

You can help AI coding agents like Claude Code use this tool by adding project instructions.

AGENTS.md or CLAUDE.md:

# Project Instructions

## `workers-fetch` command

Use `workers-fetch` command to test apps.

Run `workers-fetch --help` for usage details.

This allows AI coding agents to automatically discover and use the workers-fetch command when testing your Workers applications.

Author

Yusuke Wada https://github.com/yusukebe

License

MIT