← Workers / workers / wrangler / commands

General commands

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

docs

Open the Cloudflare developer documentation in your default browser.

npx wrangler docs [SEARCH]

• [SEARCH]string

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

• --yesboolean alias: --y

  Takes you to the docs, even if search fails

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.
• --browser boolean optional
  • Defaults to true. Automatically opens the OAuth link in your default browser. Use --browser=false to print the link instead of opening it.
• --callback-host string optional
  • Defaults to localhost. Sets the IP or hostname where Wrangler should listen for the OAuth callback. Cannot be combined with --device.
• --callback-port number optional
  • Defaults to 8976. Sets the port where Wrangler should listen for the OAuth callback. Cannot be combined with --device.
• --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.
• --device boolean optional
  • Defaults to false. Uses the OAuth 2.0 Device Authorization Grant (RFC 8628 ↗) instead of the default localhost callback flow. Refer to Use wrangler login without a local callback server.

The following global flags work on every command:

• --help boolean
  • Show help.
• --config string (not supported by Pages)
  • Path to your Wrangler configuration file.
• --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.

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:

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:

curl <LOCALHOST_URL>

To avoid this second terminal session entirely, use wrangler login --device, which does not rely on a localhost callback URL.

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:

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:

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:

# 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

If you would rather not map ports at all, use wrangler login --device, which does not start a callback server.

The default wrangler login flow needs your browser to be able to reach a temporary local server on localhost:8976. In some environments — remote SSH sessions, containers without forwarded ports, GitHub Codespaces, or otherwise restricted networks — that callback URL is unreachable from the browser, and setting up the workarounds for remote machines and containers may be difficult.

For those cases, pass --device to use the OAuth 2.0 Device Authorization Grant ↗ instead. This flow does not start a local callback server. Instead, Wrangler prints a verification URL and a short user code to the terminal, opens the verification URL in your default browser, and polls Cloudflare for an access token while you approve the request.

npx wrangler login --device

 ⛅️ wrangler 4.119.0
────────────────────
Attempting to login via OAuth Device Authorization Grant...
To authorize Wrangler, please visit:

  https://dash.cloudflare.com/oauth2/device

and enter the code:

  WDJB-MJHT

You have 5 minutes to approve this request.

Opening a link in your default browser: https://dash.cloudflare.com/oauth2/device?user_code=WDJB-MJHT
Successfully logged in.

The URL Wrangler opens in your browser has the user code already filled in, so you only need to confirm the code and approve the request. Wrangler always prints the plain verification URL and the user code as well, so you can approve on a phone or another machine, or enter the code by hand if the browser cannot open.

Wrangler stops polling after 5 minutes, or sooner if Cloudflare sets a shorter expiry on the user code. If the code expires before you approve it, run wrangler login --device again to get a new one.

Pass --browser=false to stop Wrangler from opening the browser for you and copy the verification URL yourself:

npx wrangler login --device --browser=false

--callback-host and --callback-port configure the temporary local callback server, which this flow does not use. Wrangler rejects the combination with an error rather than ignoring the flags:

npx wrangler login --device --callback-host=0.0.0.0

✘ [ERROR] `--callback-host` and `--callback-port` cannot be used with `--device`; the device authorization flow does not use a local callback server.

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:

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:

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)

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

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.

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

# 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.

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.

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)
  • Path to your Wrangler configuration file.
• --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.

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

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:

// 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)
  • Path to your Wrangler configuration file.
• --cwd string
  • Run as if Wrangler was started in the specified directory instead of the current working directory.

auth create

Create or re-authenticate a named auth profile

npx wrangler auth create [NAME]

• [NAME]string required

  Name for the auth profile

• --browserboolean default: true

  Automatically open the OAuth link in a browser

• --scopesstring

  Pick the set of applicable OAuth scopes when logging in

• --callback-hoststring default: localhost

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

• --callback-portnumber default: 8976

  Use the port for the temporary login callback server.

auth activate

Bind a named auth profile to a directory

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)

auth deactivate

Remove the auth profile binding from a directory

npx wrangler auth deactivate [DIR]

• [DIR]string

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

auth list

List all auth profiles

npx wrangler auth list

auth delete

Delete a named auth profile

npx wrangler auth delete [NAME]

• [NAME]string required

  Name of the auth profile to delete

whoami

🕵️ Retrieve your user information

npx wrangler whoami

• --accountstring

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

• --jsonboolean default: false

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

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 telemetry collection for Wrangler.

wrangler telemetry disable

Enable telemetry collection for Wrangler.

wrangler telemetry enable

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)
  • Path to your Wrangler configuration file.
• --cwd string
  • Run as if Wrangler was started in the specified directory instead of the current working directory.

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.

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

wrangler complete bash >> ~/.bashrc

wrangler complete zsh >> ~/.zshrc

wrangler complete fish >> ~/.config/fish/config.fish

wrangler complete powershell >> $PROFILE

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

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)
  • Path to your Wrangler configuration file.
• --cwd string
  • Run as if Wrangler was started in the specified directory instead of the current working directory.