wrangler kv:namespace create command
The `wrangler kv:namespace create` command creates a new KV namespace. Syntax: `wrangler kv:namespace create $NAME [--env=$ENVIRONMENT_NAME] [--preview]`. Parameters: `$NAME` is the namespace name; flags `--env $ENVIRONMENT_NAME` applies changes to specified environment; `--preview` creates a preview namespace using the `preview_id` value instead of production. The command returns output to add to the wrangler.toml, for example: `kv_namespaces = [{ binding = "MY_KV", id = "e29b263ab50e42ce9b637fa8370175e8" }]`.
wrangler kv:namespace list command
The `wrangler kv:namespace list` command lists all KV namespaces associated with an account ID. It returns JSON output with namespace objects containing `id` and `title` fields. Output can be piped through tools like `jq` for formatting.
wrangler kv:namespace delete command
The `wrangler kv:namespace delete` command deletes a KV namespace. Syntax: `wrangler kv:namespace delete --binding= [--namespace-id=]`. Either `--binding` or `--namespace-id` is required. Flags: `--env $ENVIRONMENT_NAME` applies to specified environment; `--preview` deletes preview namespace instead of production.
wrangler kv:key put command
The `wrangler kv:key put` command writes a single key-value pair to a namespace. Syntax: `wrangler kv:key put --binding= [--namespace-id=] $KEY $VALUE`. Required parameters: `$KEY` and `$VALUE`. Either `--binding` or `--namespace-id` is required. Optional flags: `--env $ENVIRONMENT_NAME` applies to specified environment; `--preview` writes to preview namespace; `--ttl` sets lifetime in seconds (minimum 60); `--expiration` sets UNIX timestamp for expiration; `--path` reads file contents as value instead of literal string.
wrangler kv:key list command
The `wrangler kv:key list` command outputs all keys in a namespace. Syntax: `wrangler kv:key list --binding= [--namespace-id=] [--prefix] [--env]`. Either `--binding` or `--namespace-id` is required. Optional flags: `--env $ENVIRONMENT_NAME` applies to specified environment; `--prefix` filters keys by prefix. Returns JSON with key names and optional expiration times.
wrangler kv:key get command
The `wrangler kv:key get` command reads a single value from a namespace by key. Syntax: `wrangler kv:key get --binding= [--env=] [--preview] [--namespace-id=] "$KEY"`. Required parameter: `$KEY`. Either `--binding` or `--namespace-id` is required. Optional flags: `--env $ENVIRONMENT_NAME` applies to specified environment; `--preview` reads from preview namespace.
wrangler kv:bulk put command
The `wrangler kv:bulk put` command writes multiple key-value pairs from a JSON file to a namespace. Syntax: `wrangler kv:bulk put --binding= [--env=] [--preview] [--namespace-id=] $FILENAME`. Required parameter: `$FILENAME` is the JSON file path. Either `--binding` or `--namespace-id` is required. Optional flags: `--env $ENVIRONMENT_NAME` applies to specified environment; `--preview` writes to preview namespace. JSON file format is an array of objects with: `key` (string, required, max 512 bytes), `value` (string, required, max 25 MB), `expiration` (int, optional, UNIX timestamp), `expiration_ttl` (int, optional, seconds, minimum 60), `base64` (bool, optional, defaults to false, decodes value as base64 before storing). If both `expiration` and `expiration_ttl` are specified, `expiration_ttl` takes precedence.
wrangler kv:bulk delete command
The `wrangler kv:bulk delete` command deletes multiple keys from a namespace using a JSON file. Syntax: `wrangler kv:bulk delete --binding= [--env=] [--preview] [--namespace-id=] $FILENAME`. Required parameter: `$FILENAME` is the JSON file with keys to delete. Either `--binding` or `--namespace-id` is required. Optional flags: `--env $ENVIRONMENT_NAME` applies to specified environment; `--preview` deletes from preview namespace. JSON file format is an array of objects with `key` (string, required) and `value` (string, required but unused for deletion, only for deserialization).
wrangler route list command
The `wrangler route list` command lists routes associated with a domain. Syntax: `wrangler route list [--env $ENVIRONMENT_NAME]`. Flag `--env $ENVIRONMENT_NAME` applies to specified environment. Returns JSON response from the List Routes API with route id, route pattern, and assigned Worker name for each route. Output can be piped through `jq` for formatting.
wrangler route delete command
The `wrangler route delete` command deletes a route. Syntax: `wrangler route delete $ID [--env $ENVIRONMENT_NAME]`. Required parameter: `$ID` is the route ID hash. Optional flag: `--env $ENVIRONMENT_NAME` applies deletion to specified environment.
wrangler subdomain command
The `wrangler subdomain` command creates or changes the `*.workers.dev` subdomain. Syntax: `wrangler subdomain <name>`.
wrangler --help output
The `wrangler --help` command (version 1.12.3) outputs all available subcommands: kv:namespace, kv:key, kv:bulk, route, secret, generate, init, build, preview, dev, publish, config, subdomain, whoami, tail, login, logout, and help.
KV bulk put JSON schema
KV bulk put accepts a JSON array with objects containing: key (string, required, max 512 bytes), value (string, required, up to 25 MB), expiration (int, optional, UNIX seconds), expiration_ttl (int, optional, seconds minimum 60), base64 (bool, optional, defaults false). For JSON data values, cast the value to a string (e.g., `"value": "{\"name\": \"test_value\"}"`).
wrangler preview with KV requires preview_id
When using KV namespaces with `wrangler preview`, a `preview_id` must be specified in the Wrangler file to avoid accidentally writing changes to the production namespace. Create a preview namespace with `wrangler kv:namespace create --preview "NAMESPACE"`. The `preview_id` can be set equal to `id` to preview with the production namespace, but this is not recommended if it would break production.
Wrangler v1 is deprecated
This documentation describes Wrangler v1 commands, which is now deprecated. Users should refer to the current Wrangler v2 documentation at /workers/wrangler/commands/.
Install Wrangler v1 with Cargo
To install Wrangler v1 using Cargo (Rust's package manager), run: cargo install wrangler
EACCES error when installing Wrangler v1 with npm
An EACCES error may occur when installing Wrangler v1 with npm due to how many systems install the npm binary. It is recommended to reinstall npm using a Node version manager like nvm or Volta.
Update Wrangler v1 with Cargo
To update Wrangler v1 using Cargo, run: cargo install wrangler --force
Update Wrangler v1 with npm
To update Wrangler v1 globally using npm, run: npm update -g @cloudflare/wrangler
Windows Cargo installation requires Perl
Windows users need to install Perl as a dependency for openssl-sys when installing Wrangler via Cargo. Strawberry Perl is the recommended Perl distribution.
Manual Wrangler v1 installation from releases
To manually install Wrangler v1, download the binary tarball for your platform from the releases page at https://github.com/cloudflare/wrangler-legacy/releases. Do not download wranglerjs-*.tar.gz as Wrangler will install that automatically. Unpack the tarball and place the Wrangler binary on your PATH, preferably /usr/local/bin for Linux/macOS or Program Files for Windows.
Install Cargo via rustup on Linux and macOS
To install Cargo on Linux and macOS systems, run: curl https://sh.rustup.rs -sSf | sh
Cargo install with system OpenSSL
To use your system's OpenSSL installation instead of the bundled copy when installing Wrangler via Cargo, run: cargo install wrangler --features sys-openssl
CLOUDFLARE_ACCOUNT_ID and account_id always respected
The CLOUDFLARE_ACCOUNT_ID environment variable and the account_id field in the Wrangler configuration file are always respected, even when an active profile is in use.
Use profiles for agency and client work
Profiles are useful for agency work where you maintain separate logins for different client accounts. Create one profile per client, bind each to that client's project directory, and commands run in each directory will automatically use the matching profile without requiring re-authentication.
Use profiles to separate staging and production accounts
When staging and production environments live in different Cloudflare accounts, create a profile for each environment, bind each profile to its environment's directory, and set the matching account_id in each project's wrangler.toml file. The account_id acts as a failsafe to prevent deploying to the wrong account even if a profile can reach multiple accounts.
wrangler auth activate command
Run `wrangler auth activate <profile-name> <directory>` to bind a profile to a directory. The profile applies to that directory and all its subdirectories. If no directory is specified, it defaults to the current working directory. A subdirectory can override the profile bound above it by activating a different profile.
wrangler auth delete command
Run `wrangler auth delete <profile-name>` to remove a profile and all of its directory bindings.
wrangler auth list command
Run `wrangler auth list` to display every profile and the directories bound to each one.
Profile resolution order in Wrangler
Wrangler selects a profile for each command using this priority order: (1) The CLOUDFLARE_API_TOKEN environment variable, which overrides all profiles; (2) The --profile flag for a single command; (3) The nearest activated ancestor directory, resolved from the directory containing the configuration file when --config is passed, otherwise from the working directory; (4) The default profile managed by wrangler login and wrangler logout.
Account selection within a profile
Within a resolved profile, Wrangler selects the target account using this order: (1) The account_id in the Wrangler configuration file, or the CLOUDFLARE_ACCOUNT_ID environment variable; (2) Otherwise, the account selected for the profile during login. If a command targets an account that the active profile cannot reach, Wrangler fails with an error naming the account and profile, and does not fall back to another account.
Profile definition
A profile is a named OAuth login that combines two things: a login created through OAuth where you choose which accounts the profile may reach (one profile can hold access to several accounts), and a directory binding that makes that directory and its subdirectories use the profile.
--profile flag for single command execution
Use the `--profile <profile-name>` flag with a Wrangler command to run that single command with a specific profile without changing any directory binding. The --profile flag is not supported by the auth, login, logout, and whoami commands.
Profiles do not apply in CI/CD environments
Authentication profiles are a local-machine convenience and do not apply in CI, containers, or other automated environments, which should authenticate using the CLOUDFLARE_API_TOKEN environment variable. When CLOUDFLARE_API_TOKEN is set, Wrangler uses it instead of any profile and you cannot create, activate, deactivate, or delete profiles.
Authentication profiles in beta
Authentication profiles are currently in beta. The commands and their behavior may change.
wrangler auth create command
Run `wrangler auth create <name>` to create a new authentication profile. Wrangler starts an OAuth flow where you choose which Cloudflare accounts the profile may access. Run the command again with the same name to re-authenticate an existing profile after its token expires.
wrangler auth deactivate command
Run `wrangler auth deactivate <directory>` to remove the profile binding from a directory. The directory will then use the profile bound in a parent directory, or fall back to the default profile.
wrangler ai-search commands available
The wrangler ai-search command namespace provides the following commands: wrangler ai-search create (create a new instance with an interactive wizard), wrangler ai-search list (list all instances in your account), wrangler ai-search get (get details of a specific instance), wrangler ai-search update (update the configuration of an instance), wrangler ai-search delete (delete an instance), wrangler ai-search search (run a search query against an instance), and wrangler ai-search stats (get usage statistics for an instance).
wrangler ai-search search command usage
The wrangler ai-search search command accepts an instance name as the first argument and supports --query flag to specify the search query string to run against that instance.
wrangler ai-search create command flags
The wrangler ai-search create command supports --type flag (accepts 'r2' or 'web' as source type) and --source flag (specifies the data source). The command also guides through setup interactively to choose a name, source type, and data source. All options can be passed as flags for non-interactive use.
wrangler ai-search instance commands support --namespace flag
Instance-level commands support a --namespace flag to interact with instances inside a specific namespace from the CLI. Example: wrangler ai-search list --namespace docs-production
wrangler ai-search namespace list with pagination and search
List namespaces with pagination or filter by name or description using: wrangler ai-search namespace list --search docs --page 1 --per-page 10
wrangler ai-search namespace commands support --json flag
The list, create, get, and update commands support the --json flag to return structured output that automation and AI agents can parse directly.
wrangler ai-search namespace create example
Create a namespace for a new application or tenant with the command: wrangler ai-search namespace create docs-production --description "Production documentation search"
wrangler ai-search namespace commands
The following namespace-level commands are available: wrangler ai-search namespace list (list AI Search namespaces), wrangler ai-search namespace create (create a new AI Search namespace), wrangler ai-search namespace get (get details for a namespace), wrangler ai-search namespace update (update a namespace description), and wrangler ai-search namespace delete (delete an AI Search namespace).
wrangler triggers deploy command deploys triggers
The `wrangler triggers deploy` command deploys triggers for a Worker. Minimum required wrangler version is 3.40.0. For versions before 3.73.0, the `--x-versions` flag is needed.
wrangler deployments status shows current deployment status
The `wrangler deployments status` command shows the current status of Worker deployments. Minimum required wrangler version is 3.40.0. For versions before 3.73.0, the `--x-versions` flag is needed.
wrangler rollback command reverts to previous Worker version
The `wrangler rollback` command immediately creates a new deployment with a specified version of a Worker and becomes the active deployment across all deployed routes and domains. This change does not affect work in the local development environment. Syntax: `wrangler rollback [<VERSION_ID>] [OPTIONS]`. VERSION_ID (string, optional) is the ID of the version to roll back to; if not supplied, defaults to the version uploaded before the latest version.
wrangler rollback options
The `wrangler rollback` command includes options: `--name` (string, optional) specifies a specific Worker rather than inheriting from Wrangler configuration file; `--message` (string, optional) adds message for rollback, accepts empty string, when specified skips interactive prompts for rollback confirmation and message.
wrangler types command generates TypeScript types
The `wrangler types` command generates types based on Worker configuration, including `Env` types based on bindings, module rules, and runtime types based on `compatibility_date` and `compatibility_flags`. Syntax: `wrangler types [<PATH>] [OPTIONS]`. By default, generates types for bindings from all environments defined in configuration file, ensuring the generated `Env` type includes all bindings that might be used across different deployment environments.
wrangler types command interface and inclusion options
The `wrangler types` command includes options: `--env-interface` (string, default `Env`) specifies the name of the interface to generate for the environment object, not valid if the Worker uses Service Worker syntax; `--include-runtime` (boolean, default true) generates runtime types based on `compatibility_date` and `compatibility_flags` in config file; `--include-env` (boolean, default true) generates `Env` types based on Worker bindings.
wrangler types command vars and checking options
The `wrangler types` command includes options: `--strict-vars` (boolean, optional, default true) controls the types generated for `vars` bindings; if true (default), generates literal and union types (e.g., `myVar: 'my dev variable' | 'my prod variable'`); if false, generates generic types (e.g., `myVar: string`), useful when variables change frequently; `--check` (boolean, optional) checks if generated types at specified path are up-to-date without regenerating, exits with code 0 if up-to-date or code 1 if out-of-date, useful for CI/CD pipelines and pre-commit hooks.
wrangler check startup analyzes Worker startup phase
The `wrangler check startup` command analyzes a Worker's startup phase. Wrangler reports bundle size and a summary of local CPU activity, and saves a detailed CPU profile. The profile includes metrics: Profile window (elapsed time between start and end of profiling), Sampled time (total time represented by captured CPU samples), Active (sampled time Worker was not idle including garbage collection), Idle (sampled time Worker was idle), Samples (number of CPU samples captured). The generated `.cpuprofile` file can be imported into Chrome DevTools or opened directly in VS Code to view a flamegraph.
wrangler types command config option for bound services
The `wrangler types` command includes option: `--config` or `-c` (string[], optional) specifies path(s) to Wrangler configuration file; if the Worker has service bindings or bindings to Durable Objects, provide paths to those configuration files so generated `Env` type includes RPC types. Example: `wrangler types -c wrangler.toml -c ../bound-worker/wrangler.toml` generates `Env` type including `SERVICE_BINDING: Service<import("../bound-worker/src/index").Entrypoint>`.
wrangler check startup options
The `wrangler check startup` command includes options: `--args` (string, optional) customizes how the command builds the Worker for analysis by providing exact arguments used when deploying with `wrangler deploy` or Pages project with `wrangler pages functions build`; `--worker` (string, optional) provides a Worker bundle to analyze if Wrangler is not used to deploy, should be a file path to a serialized multipart upload; `--pages` (boolean, optional) treats project as Pages project if no Wrangler config file with `pages_build_output_dir` exists.
wrangler check startup local measurement caveat
The `wrangler check startup` command measures performance locally on the user's machine, which has a different CPU than when the Worker runs on Cloudflare, meaning results can vary widely. The summary and CPU profile help understand where the Worker spends time during startup, but the local profile duration should not be expected to match the Worker's actual startup time on Cloudflare.
wrangler init command syntax and options
The `wrangler init` command creates a new project via the create-cloudflare-cli (C3) tool. Syntax: `wrangler init [<NAME>] [OPTIONS]`. NAME is optional (defaults to the name of the working directory) and is both the directory name and the `name` property in the generated Wrangler configuration. Options include: `--yes` (boolean, optional) to answer yes to any prompts; `--from-dash` (string, optional) to fetch a Worker initialized from the dashboard by passing the Worker name, though this command will not automatically sync changes made to the dashboard after use.
wrangler dev command for local development
The `wrangler dev` command starts a local server for developing your Worker. Syntax: `wrangler dev [<SCRIPT>] [OPTIONS]`. SCRIPT (string, optional) is the path to an entry point for your Worker, only required if the Wrangler configuration file does not include a `main` key. When running, send HTTP requests to `localhost:8787` and the Worker should execute as expected. Console.log messages and exceptions appear in the terminal. The command runs the local workerd runtime with TZ=UTC to match the production Cloudflare runtime, so Date and Intl APIs observe UTC during local development regardless of the machine's timezone.
wrangler dev options for configuration and environment
The `wrangler dev` command includes options for configuration and environment: `--name` (string, optional) specifies the Worker name; `--config` or `-c` (string[], optional) specifies path(s) to Wrangler configuration file, supporting multiple configs to run multiple Workers in one session where the first config is the primary Worker exposed over HTTP and remaining configs are accessible via service binding; `--env` (string, optional) specifies a specific environment; `--compatibility-date` (string, optional, format yyyy-mm-dd) determines which version of the Workers runtime is used; `--compatibility-flags` or `--compatibility-flag` (string[], optional) specifies flags for compatibility checks; `--latest` (boolean, default true, optional) uses the latest version of the Workers runtime.
wrangler dev options for network and local server
The `wrangler dev` command includes options for network configuration: `--ip` (string, optional) specifies the IP address to listen on (defaults to localhost); `--port` (number, optional) specifies the port to listen on; `--inspector-port` (number, optional) specifies the port for devtools to connect to; `--local-protocol` (http|https, default http, optional) specifies the protocol to listen to requests on; `--https-key-path` (string, optional) specifies the path to a custom certificate key; `--https-cert-path` (string, optional) specifies the path to a custom certificate; `--local-upstream` (string, optional) specifies the host to act as origin in local mode (defaults to dev.host or route); `--upstream-protocol` (http|https, default https, optional) specifies the protocol to forward requests to host on.