Skip to content
Cloudflare Docs
DirectoryAPISDKsChangelog

General commands

General Wrangler commands for authentication, telemetry, and shell completions.

docs

Open the Cloudflare developer documentation in your default browser.

Terminal window
npx wrangler docs [SEARCH]
  • [SEARCH] string

    Enter search terms (e.g. the wrangler command) you want to know more about

  • --yes boolean alias: --y

    Takes you to the docs, even if search fails

Global flags
  • --v boolean alias: --version

    Show version number

  • --cwd string

    Run as if Wrangler was started in the specified directory instead of the current working directory

  • --config string alias: --c

    Path to Wrangler configuration file

  • --env string alias: --e

    Environment to use for operations, and for selecting .env and .dev.vars files

  • --env-file string

    Path to an .env file to load - can be specified multiple times - values from earlier files are overridden by values in later files

  • --experimental-provision boolean aliases: --x-provision default: true

    Experimental: Enable automatic resource provisioning

  • --experimental-auto-create boolean alias: --x-auto-create default: true

    Automatically provision draft bindings with new resources

  • --install-skills boolean default: false

    Install Cloudflare skills for detected AI coding agents before running the command

  • --profile string

    Use a specific auth profile

login

Authorize Wrangler with your Cloudflare account using OAuth. Wrangler will attempt to automatically open your web browser to login with your Cloudflare account.

If you prefer to use API tokens for authentication, such as in headless or continuous integration environments, refer to Running Wrangler in CI/CD.

wrangler login [OPTIONS]
  • --scopes-list string optional
    • List all the available OAuth scopes with descriptions.
  • --scopes string optional
    • Allows to choose your set of OAuth scopes. The set of scopes must be entered in a whitespace-separated list, for example, npx wrangler login --scopes account:read user:read.
  • --callback-host string optional
    • Defaults to localhost. Sets the IP or hostname where Wrangler should listen for the OAuth callback.
  • --callback-port string optional
    • Defaults to 8976. Sets the port where Wrangler should listen for the OAuth callback.
  • --use-keyring boolean optional
    • Stores the OAuth credentials in your operating system keychain instead of the default plaintext TOML file. Refer to Storing OAuth credentials in the OS keychain for details. Use --no-use-keyring to opt back out. The choice is persisted across Wrangler invocations.

The following global flags work on every command:

  • --help boolean
    • Show help.
  • --config string (not supported by Pages)
  • --cwd string
    • Run as if Wrangler was started in the specified directory instead of the current working directory.

If Wrangler fails to open a browser, you can copy and paste the URL generated by wrangler login in your terminal into a browser and log in.

Use wrangler login on a remote machine

If you are using Wrangler from a remote machine, but run the login flow from your local browser, you will receive the following error message after logging in:This site can't be reached.

To finish the login flow, run wrangler login and go through the login flow in the browser:

Terminal window
npx wrangler login
 ⛅️ wrangler 2.1.6
-------------------
Attempting to login via OAuth...
Opening a link in your default browser: https://dash.cloudflare.com/oauth2/auth?xyz...

The browser login flow will redirect you to a localhost URL on your machine.

Leave the login flow active. Open a second terminal session. In that second terminal session, use curl or an equivalent request library on the remote machine to fetch this localhost URL. Copy and paste the localhost URL that was generated during the wrangler login flow and run:

Terminal window
curl <LOCALHOST_URL>

Use wrangler login in a container

The Cloudflare OAuth provider will always redirect to a callback server at localhost:8976. If you are running Wrangler inside a container, this server might not be accessible from your host machine's browser - even after authorizing the connection, your login command will hang.

You must configure your container to map port 8976 on your host machine to the Wrangler OAuth callback server's port (8976 by default).

For example, if you are running Wrangler in a Docker container:

Terminal window
docker run -p 8976:8976 <your-image>

And when you run npx wrangler login inside your container, set the callback host to listen on all network interfaces:

Terminal window
npx wrangler login --callback-host=0.0.0.0

Now when the browser redirects to localhost:8976, the request will be forwarded to Wrangler running inside the container on 0.0.0.0:8976.

If you need to use a different port inside the container, use --callback-port as well and adjust your port mapping accordingly, for example:

Terminal window
# When starting your container
docker run -p 8976:9000 <your-image>


# Inside the container
npx wrangler login --callback-host=0.0.0.0 --callback-port=9000

Storing OAuth credentials in the OS keychain

By default, Wrangler stores the OAuth access token and refresh token returned by wrangler login in a plaintext TOML file under the global Wrangler config directory (typically ~/.config/.wrangler/config/default.toml). Pass --use-keyring to opt in to a more secure storage path that uses your operating system keychain:

Terminal window
npx wrangler login --use-keyring

When --use-keyring is enabled, Wrangler writes the credentials into an AES-256-GCM ↗-encrypted file (default.enc, alongside the legacy default.toml location) and stores the 32-byte encryption key in your OS keychain:

  • macOS uses the built-in Keychain ↗ via /usr/bin/security.
  • Linux uses libsecret ↗ via the secret-tool CLI from the libsecret-tools package. Wrangler will print a per-distro install hint if secret-tool is not available.
  • Windows uses Credential Manager ↗ via @napi-rs/keyring ↗, which Wrangler installs lazily the first time you opt in (≈1.9 MB one-time download). In non-interactive environments such as CI, install the binding ahead of time with npm install -g @napi-rs/keyring@<version> or stay on the default plaintext path.

If a plaintext credentials file exists when you first opt in, Wrangler reads it, encrypts the contents into the new .enc file, and deletes the plaintext file.

The choice is persisted across Wrangler invocations. To verify where credentials are currently stored, run wrangler whoami:

Terminal window
npx wrangler whoami
👋 You are logged in with an OAuth Token, associated with the email user@example.com.
🔐 Credentials are stored in: Encrypted file (~/.config/.wrangler/config/default.enc) with key in macOS Keychain (service=wrangler, account=default)

Opting out

To opt back out, pass --no-use-keyring:

Terminal window
npx wrangler login --no-use-keyring

Opt-out deletes the encrypted file and the keychain entry. Wrangler intentionally does not decrypt the existing credentials onto disk — writing plaintext during opt-out would defeat the at-rest protection you just chose to disable. The subsequent login flow writes fresh credentials into the plaintext TOML file.

Per-process override

The environment variable CLOUDFLARE_AUTH_USE_KEYRING overrides the persistent preference for a single invocation:

Terminal window
# Force the keychain backend for this command only
CLOUDFLARE_AUTH_USE_KEYRING=true npx wrangler deploy


# Force the plaintext file backend for this command only
CLOUDFLARE_AUTH_USE_KEYRING=false npx wrangler deploy

When the environment variable is set to true and the keychain backend is unavailable (for example, secret-tool is missing on Linux), Wrangler exits with an error rather than silently falling back to the plaintext file. With only the persistent preference set, Wrangler falls back to the plaintext file and prints a one-time warning so a broken keychain never locks you out.

Compatibility

The --use-keyring opt-in does not change how API tokens are resolved: CLOUDFLARE_API_TOKEN and CLOUDFLARE_API_KEY/CLOUDFLARE_EMAIL continue to take priority over any stored OAuth credentials, and the Running Wrangler in CI/CD guidance still applies for non-interactive environments.

logout

Remove Wrangler's authorization for accessing your account. This command will invalidate your current OAuth token and delete the stored credentials. When keychain storage is active, both the encrypted credentials file and the keychain entry are removed.

wrangler logout

The following global flags work on every command:

  • --help boolean
    • Show help.
  • --config string (not supported by Pages)
  • --cwd string
    • Run as if Wrangler was started in the specified directory instead of the current working directory.

If you are using CLOUDFLARE_API_TOKEN instead of OAuth, and you can logout by deleting your API token in the Cloudflare dashboard:

  1. In the Cloudflare dashboard, go to the Account API tokens page.

    Go to Account API tokens

  2. Select the three-dot menu on your Wrangler token.

  3. Select Delete.

auth

Manage authentication, including named authentication profiles for working across multiple accounts.

auth token

Retrieve your current authentication token or credentials for use with other tools and scripts.

wrangler auth token [OPTIONS]
  • --json boolean optional
    • Return output as JSON with token type information. This also enables retrieving API key/email credentials.

The command returns whichever authentication method is currently configured, in the following order of precedence:

  • API token from CLOUDFLARE_API_TOKEN environment variable
  • API key/email from CLOUDFLARE_API_KEY and CLOUDFLARE_EMAIL environment variables (requires --json flag, since this method uses two values instead of a single token)
  • OAuth token from wrangler login (automatically refreshed if expired)

When using --json, the output includes the token type:

JSONC
// API token
{ "type": "api_token", "token": "..." }


// OAuth token
{ "type": "oauth", "token": "..." }


// API key/email (only available with --json)
{ "type": "api_key", "key": "...", "email": "..." }

An error is returned if no authentication method is available, or if API key/email is configured without --json.

The following global flags work on every command:

  • --help boolean
    • Show help.
  • --config string (not supported by Pages)
  • --cwd string
    • Run as if Wrangler was started in the specified directory instead of the current working directory.

auth create


Experimental

Create or re-authenticate a named auth profile

Terminal window
npx wrangler auth create [NAME]
  • [NAME] string required

    Name for the auth profile

  • --browser boolean default: true

    Automatically open the OAuth link in a browser

  • --scopes string

    Pick the set of applicable OAuth scopes when logging in

  • --callback-host string default: localhost

    Use the ip or host address for the temporary login callback server.

  • --callback-port number default: 8976

    Use the port for the temporary login callback server.

Global flags
  • --v boolean alias: --version

    Show version number

  • --cwd string

    Run as if Wrangler was started in the specified directory instead of the current working directory

  • --config string alias: --c

    Path to Wrangler configuration file

  • --env string alias: --e

    Environment to use for operations, and for selecting .env and .dev.vars files

  • --env-file string

    Path to an .env file to load - can be specified multiple times - values from earlier files are overridden by values in later files

  • --experimental-provision boolean aliases: --x-provision default: true

    Experimental: Enable automatic resource provisioning

  • --experimental-auto-create boolean alias: --x-auto-create default: true

    Automatically provision draft bindings with new resources

  • --install-skills boolean default: false

    Install Cloudflare skills for detected AI coding agents before running the command

  • --profile string

    Use a specific auth profile

auth activate


Experimental

Bind a named auth profile to a directory

Terminal window
npx wrangler auth activate [NAME] [DIR]
  • [NAME] string required

    Name of the auth profile to activate

  • [DIR] string

    Directory to bind the profile to (defaults to current directory)

Global flags
  • --v boolean alias: --version

    Show version number

  • --cwd string

    Run as if Wrangler was started in the specified directory instead of the current working directory

  • --config string alias: --c

    Path to Wrangler configuration file

  • --env string alias: --e

    Environment to use for operations, and for selecting .env and .dev.vars files

  • --env-file string

    Path to an .env file to load - can be specified multiple times - values from earlier files are overridden by values in later files

  • --experimental-provision boolean aliases: --x-provision default: true

    Experimental: Enable automatic resource provisioning

  • --experimental-auto-create boolean alias: --x-auto-create default: true

    Automatically provision draft bindings with new resources

  • --install-skills boolean default: false

    Install Cloudflare skills for detected AI coding agents before running the command

  • --profile string

    Use a specific auth profile

auth deactivate


Experimental

Remove the auth profile binding from a directory

Terminal window
npx wrangler auth deactivate [DIR]
  • [DIR] string

    Directory to unbind (defaults to current directory). Must be the exact directory the profile was bound to.

Global flags
  • --v boolean alias: --version

    Show version number

  • --cwd string

    Run as if Wrangler was started in the specified directory instead of the current working directory

  • --config string alias: --c

    Path to Wrangler configuration file

  • --env string alias: --e

    Environment to use for operations, and for selecting .env and .dev.vars files

  • --env-file string

    Path to an .env file to load - can be specified multiple times - values from earlier files are overridden by values in later files

  • --experimental-provision boolean aliases: --x-provision default: true

    Experimental: Enable automatic resource provisioning

  • --experimental-auto-create boolean alias: --x-auto-create default: true

    Automatically provision draft bindings with new resources

  • --install-skills boolean default: false

    Install Cloudflare skills for detected AI coding agents before running the command

  • --profile string

    Use a specific auth profile

auth list


Experimental

List all auth profiles

Terminal window
npx wrangler auth list

Global flags
  • --v boolean alias: --version

    Show version number

  • --cwd string

    Run as if Wrangler was started in the specified directory instead of the current working directory

  • --config string alias: --c

    Path to Wrangler configuration file

  • --env string alias: --e

    Environment to use for operations, and for selecting .env and .dev.vars files

  • --env-file string

    Path to an .env file to load - can be specified multiple times - values from earlier files are overridden by values in later files

  • --experimental-provision boolean aliases: --x-provision default: true

    Experimental: Enable automatic resource provisioning

  • --experimental-auto-create boolean alias: --x-auto-create default: true

    Automatically provision draft bindings with new resources

  • --install-skills boolean default: false

    Install Cloudflare skills for detected AI coding agents before running the command

  • --profile string

    Use a specific auth profile

auth delete


Experimental

Delete a named auth profile

Terminal window
npx wrangler auth delete [NAME]
  • [NAME] string required

    Name of the auth profile to delete

Global flags
  • --v boolean alias: --version

    Show version number

  • --cwd string

    Run as if Wrangler was started in the specified directory instead of the current working directory

  • --config string alias: --c

    Path to Wrangler configuration file

  • --env string alias: --e

    Environment to use for operations, and for selecting .env and .dev.vars files

  • --env-file string

    Path to an .env file to load - can be specified multiple times - values from earlier files are overridden by values in later files

  • --experimental-provision boolean aliases: --x-provision default: true

    Experimental: Enable automatic resource provisioning

  • --experimental-auto-create boolean alias: --x-auto-create default: true

    Automatically provision draft bindings with new resources

  • --install-skills boolean default: false

    Install Cloudflare skills for detected AI coding agents before running the command

  • --profile string

    Use a specific auth profile

whoami

🕵️ Retrieve your user information

Terminal window
npx wrangler whoami
  • --account string

    Show membership information for the given account (id or name).

  • --json boolean default: false

    Return user information as JSON. Exits with a non-zero status if not authenticated.

Global flags
  • --v boolean alias: --version

    Show version number

  • --cwd string

    Run as if Wrangler was started in the specified directory instead of the current working directory

  • --config string alias: --c

    Path to Wrangler configuration file

  • --env string alias: --e

    Environment to use for operations, and for selecting .env and .dev.vars files

  • --env-file string

    Path to an .env file to load - can be specified multiple times - values from earlier files are overridden by values in later files

  • --experimental-provision boolean aliases: --x-provision default: true

    Experimental: Enable automatic resource provisioning

  • --experimental-auto-create boolean alias: --x-auto-create default: true

    Automatically provision draft bindings with new resources

  • --install-skills boolean default: false

    Install Cloudflare skills for detected AI coding agents before running the command

  • --profile string

    Use a specific auth profile

telemetry

Cloudflare collects anonymous usage data to improve Wrangler. You can learn more about this in our data policy ↗.

You can manage sharing of usage data at any time using these commands.

disable

Disable telemetry collection for Wrangler.

wrangler telemetry disable

enable

Enable telemetry collection for Wrangler.

wrangler telemetry enable

status

Check whether telemetry collection is currently enabled. The return result is specific to the directory where you have run the command.

This will resolve the global status set by wrangler telemetry disable / enable, the environment variable WRANGLER_SEND_METRICS, and the send_metrics key in the Wrangler configuration file.

wrangler telemetry status

The following global flags work on every command:

  • --help boolean
    • Show help.
  • --config string (not supported by Pages)
  • --cwd string
    • Run as if Wrangler was started in the specified directory instead of the current working directory.

complete

Generate shell completion scripts for Wrangler commands. Shell completions allow you to autocomplete commands, subcommands, and flags by pressing Tab as you type.

wrangler complete <SHELL>
  • SHELL string required
    • The shell to generate completions for. Supported values: bash, zsh, fish, powershell.

Setup

Generate and add the completion script to your shell configuration file:

Terminal window
wrangler complete bash >> ~/.bashrc

Then restart your terminal or run source ~/.bashrc.

Usage

After setup, press Tab to autocomplete commands, subcommands, and flags:

Terminal window
wrangler d<TAB>          # completes to 'deploy', 'dev', 'd1', etc.
wrangler kv <TAB>        # shows subcommands: namespace, key, bulk

The following global flags work on every command:

  • --help boolean
    • Show help.
  • --config string (not supported by Pages)
  • --cwd string
    • Run as if Wrangler was started in the specified directory instead of the current working directory.