Skip to content
Cloudflare Docs
Docs DirectoryAPIsSDKs

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

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.

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

logout

Remove Wrangler's authorization for accessing your account. This command will invalidate your current OAuth token.

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

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.

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

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.