---
title: General commands
description: General Wrangler commands for authentication, telemetry, and shell completions.
image: https://edgetunnel-b2h.pages.dev/dev-products-preview.png
---

> Documentation Index  
> Fetch the complete documentation index at: https://edgetunnel-b2h.pages.dev/workers/llms.txt  
> Use this file to discover all available pages before exploring further. 

[Skip to content](#%5Ftop) 

# General commands

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

## `docs`

Open the Cloudflare developer documentation in your default browser.

* [  npm ](#tab-panel-13294)
* [  pnpm ](#tab-panel-13295)
* [  yarn ](#tab-panel-13296)

```sh
npx wrangler docs [SEARCH]
```

```sh
pnpm wrangler docs [SEARCH]
```

```sh
yarn 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](https://edgetunnel-b2h.pages.dev/workers/ci-cd/).

```txt
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](#storing-oauth-credentials-in-the-os-keychain) for details. Use `--no-use-keyring` to opt back out. The choice is persisted across Wrangler invocations.

Note

`wrangler login` uses all the available scopes by default if no flags are provided.

The following global flags work on every command:

* `--help` ` boolean `  
  * Show help.
* `--config` ` string ` (not supported by Pages)  
  * Path to your [Wrangler configuration file](https://edgetunnel-b2h.pages.dev/workers/wrangler/configuration/).
* `--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:

```sh
npx wrangler login
```

```sh
 ⛅️ 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:

```sh
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:

```sh
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:

```sh
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:

```sh
# 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:

```sh
npx wrangler login --use-keyring
```

When `--use-keyring` is enabled, Wrangler writes the credentials into an [AES-256-GCM ↗](https://en.wikipedia.org/wiki/Galois/Counter%5FMode)\-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 ↗](https://support.apple.com/guide/keychain-access/welcome/mac) via `/usr/bin/security`.
* **Linux** uses [libsecret ↗](https://wiki.gnome.org/Projects/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 ↗](https://support.microsoft.com/en-us/windows/accessing-credential-manager-1b5c916a-6a16-889f-8581-fc16e8165ac0) via [@napi-rs/keyring ↗](https://www.npmjs.com/package/@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`:

```sh
npx wrangler whoami
```

```sh
👋 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`:

```sh
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:

```sh
# 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](https://edgetunnel-b2h.pages.dev/workers/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](#storing-oauth-credentials-in-the-os-keychain) is active, both the encrypted credentials file and the keychain entry are removed.

```txt
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](https://edgetunnel-b2h.pages.dev/workers/wrangler/configuration/).
* `--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** ](https://dash.cloudflare.com/?to=/:account/api-tokens)
2. Select the three-dot menu on your Wrangler token.
3. Select **Delete**.

---

## `auth`

Manage authentication, including named [authentication profiles](https://edgetunnel-b2h.pages.dev/workers/wrangler/profiles/) for working across multiple accounts.

### `auth token`

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

```txt
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**

```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)  
  * Path to your [Wrangler configuration file](https://edgetunnel-b2h.pages.dev/workers/wrangler/configuration/).
* `--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

* [  npm ](#tab-panel-13297)
* [  pnpm ](#tab-panel-13298)
* [  yarn ](#tab-panel-13299)

```sh
npx wrangler auth create [NAME]
```

```sh
pnpm wrangler auth create [NAME]
```

```sh
yarn 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

* [  npm ](#tab-panel-13300)
* [  pnpm ](#tab-panel-13301)
* [  yarn ](#tab-panel-13302)

```sh
npx wrangler auth activate [NAME] [DIR]
```

```sh
pnpm wrangler auth activate [NAME] [DIR]
```

```sh
yarn 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

* [  npm ](#tab-panel-13303)
* [  pnpm ](#tab-panel-13304)
* [  yarn ](#tab-panel-13305)

```sh
npx wrangler auth deactivate [DIR]
```

```sh
pnpm wrangler auth deactivate [DIR]
```

```sh
yarn 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

* [  npm ](#tab-panel-13306)
* [  pnpm ](#tab-panel-13307)
* [  yarn ](#tab-panel-13308)

```sh
npx wrangler auth list
```

```sh
pnpm wrangler auth list
```

```sh
yarn 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

* [  npm ](#tab-panel-13309)
* [  pnpm ](#tab-panel-13310)
* [  yarn ](#tab-panel-13311)

```sh
npx wrangler auth delete [NAME]
```

```sh
pnpm wrangler auth delete [NAME]
```

```sh
yarn 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

* [  npm ](#tab-panel-13312)
* [  pnpm ](#tab-panel-13313)
* [  yarn ](#tab-panel-13314)

```sh
npx wrangler whoami
```

```sh
pnpm wrangler whoami
```

```sh
yarn 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 ↗](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler/telemetry.md).

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

### `disable`

Disable telemetry collection for Wrangler.

```txt
wrangler telemetry disable
```

### `enable`

Enable telemetry collection for Wrangler.

```txt
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](https://edgetunnel-b2h.pages.dev/workers/wrangler/system-environment-variables/#supported-environment-variables), and the [send\_metrics](https://edgetunnel-b2h.pages.dev/workers/wrangler/configuration/#top-level-only-keys) key in the [Wrangler configuration file](https://edgetunnel-b2h.pages.dev/workers/wrangler/configuration/).

```txt
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](https://edgetunnel-b2h.pages.dev/workers/wrangler/configuration/).
* `--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.

```txt
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:

* [ Bash ](#tab-panel-13290)
* [ Zsh ](#tab-panel-13291)
* [ Fish ](#tab-panel-13292)
* [ PowerShell ](#tab-panel-13293)

```sh
wrangler complete bash >> ~/.bashrc
```

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

```sh
wrangler complete zsh >> ~/.zshrc
```

Then restart your terminal or run `source ~/.zshrc`.

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

Then restart your terminal or run `source ~/.config/fish/config.fish`.

**PowerShell**

```powershell
wrangler complete powershell >> $PROFILE
```

Then restart PowerShell or run `. $PROFILE`.

### Usage

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

```sh
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](https://edgetunnel-b2h.pages.dev/workers/wrangler/configuration/).
* `--cwd` ` string `  
  * Run as if Wrangler was started in the specified directory instead of the current working directory.

```json
{"@context":"https://schema.org","@type":"TechArticle","@id":"https://edgetunnel-b2h.pages.dev/workers/wrangler/commands/general/#page","headline":"General commands · Cloudflare Workers docs","description":"General Wrangler commands for authentication, telemetry, and shell completions.","url":"https://edgetunnel-b2h.pages.dev/workers/wrangler/commands/general/","inLanguage":"en","image":"https://edgetunnel-b2h.pages.dev/dev-products-preview.png","dateModified":"2026-07-03","publisher":{"@type":"Organization","name":"Cloudflare","url":"https://www.cloudflare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://edgetunnel-b2h.pages.dev/#website","name":"Cloudflare Docs","url":"https://edgetunnel-b2h.pages.dev/"}}
{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/workers/","name":"Workers"}},{"@type":"ListItem","position":3,"item":{"@id":"/workers/wrangler/","name":"Wrangler"}},{"@type":"ListItem","position":4,"item":{"@id":"/workers/wrangler/commands/","name":"Commands"}},{"@type":"ListItem","position":5,"item":{"@id":"/workers/wrangler/commands/general/","name":"General commands"}}]}
```