Commands (3)·续1

Commands (3)·续1

kv_namespaces

If you are using kv_namespaces with wrangler preview, you will need to specify a preview_id in your Wrangler file before you can start the session. This is so that you do not accidentally write changes to your production namespace while you are developing. You may make preview_id equal to id if you would like to preview with your production namespace, but you should ensure that you are not writing values to KV that would break your production Worker.

To create a preview_id run:

wrangler kv:namespace create --preview "NAMESPACE"

Previewing on Windows Subsystem for Linux (WSL 1/2)

Setting $BROWSER to your browser binary

WSL is a Linux environment, so Wrangler attempts to invoke xdg-open to open your browser. To make wrangler preview work with WSL, you should set your $BROWSER to the path of your browser binary:

export BROWSER="/mnt/c/tools/firefox.exe"
wrangler preview

Spaces in filepaths are not common in Linux, and some programs like xdg-open will break on paths with spaces ↗︎. You can work around this by linking the binary to your /usr/local/bin:

ln -s "/mnt/c/Program Files/Mozilla Firefox/firefox.exe" firefox
export BROWSER=firefox

Setting $BROWSER to `wsl-open`

Another option is to install wsl-open ↗︎ and set the $BROWSER env variable to wsl-open via wsl-open -w. This ensures that xdg-open uses wsl-open when it attempts to open your browser.

If you are using WSL 2, you will need to install wsl-open following their standalone method ↗︎ rather than through npm. This is because their npm package has not yet been updated with WSL 2 support.

`route`

List or delete a route associated with a domain:

wrangler route list [--env $ENVIRONMENT_NAME]

Default values indicated by =value.

--env $ENVIRONMENT_NAME optional
If defined, the changes will only apply to the specified environment. Refer to Environments for more information.

This command will forward the JSON response from the List Routes API. Each object within the JSON list will include the route id, route pattern, and the assigned Worker name for the route. Piping this through a tool such as jq will render the output nicely.

wrangler route delete $ID [--env $ENVIRONMENT_NAME]

Default values indicated by =value.

$ID required
The hash of the route ID to delete.
--env $ENVIRONMENT_NAME optional
If defined, the changes will only apply to the specified environment. Refer to Environments for more information.

subdomain

Create or change your *.workers.dev ↗︎ subdomain.

wrangler subdomain <name>

secret

Interact with your secrets.

`put`

Create or replace a secret.

wrangler secret put <name> --env ENVIRONMENT_NAME
Enter the secret text you would like assigned to the variable name on the Worker named my-worker-ENVIRONMENT_NAME:

You will be prompted to input the secret's value. This command can receive piped input, so the following example is also possible:

echo "-----BEGIN PRIVATE KEY-----\nM...==\n-----END PRIVATE KEY-----\n" | wrangler secret put PRIVATE_KEY

name
The variable name to be accessible in the script.
--env $ENVIRONMENT_NAME optional
If defined, the changes will only apply to the specified environment. Refer to Environments for more information.

`delete`

Delete a secret from a specific script.

wrangler secret delete <name> --env ENVIRONMENT_NAME

name
The variable name to be accessible in the script.
--env $ENVIRONMENT_NAME optional
If defined, the changes will only apply to the specified environment. Refer to Environments for more information.

`list`

List all the secret names bound to a specific script.

wrangler secret list --env ENVIRONMENT_NAME

--env $ENVIRONMENT_NAME optional
If defined, only the specified environment's secrets will be listed. Refer to Environments for more information.

kv

The kv subcommand allows you to store application data in the Cloudflare network to be accessed from Workers using Workers KV ↗︎. KV operations are scoped to your account, so in order to use any of these commands, you:

must configure an account_id in your project's Wrangler file.
run all wrangler kv:<command> operations in your terminal from the project's root directory.

Getting started

To use Workers KV with your Worker, the first thing you must do is create a KV namespace. This is done with the kv:namespace subcommand.

The kv:namespace subcommand takes a new binding name as its argument. A Workers KV namespace will be created using a concatenation of your Worker’s name (from your Wrangler file) and the binding name you provide:

wrangler kv:namespace create "MY_KV"

🌀  Creating namespace with title "my-site-MY_KV"
✨  Success!
Add the following to your configuration file:
kv_namespaces = [
  { binding = "MY_KV", id = "e29b263ab50e42ce9b637fa8370175e8" }
]

Successful operations will print a new configuration block that should be copied into your Wrangler file. Add the output to the existing kv_namespaces configuration if already present. You can now access the binding from within a Worker:

let value = await MY_KV.get("my-key");

To write a value to your KV namespace using Wrangler, run the wrangler kv:key put subcommand.

wrangler kv:key put --binding=MY_KV "key" "value"

✨  Success

Instead of --binding, you may use --namespace-id to specify which KV namespace should receive the operation:

wrangler kv:key put --namespace-id=e29b263ab50e42ce9b637fa8370175e8 "key" "value"

✨  Success

Additionally, KV namespaces can be used with environments. This is useful for when you have code that refers to a KV binding like MY_KV, and you want to be able to have these bindings point to different namespaces (like one for staging and one for production).

A Wrangler file with two environments:

{
    "env": {
        "staging": {
            "kv_namespaces": [
                {
                    "binding": "MY_KV",
                    "id": "e29b263ab50e42ce9b637fa8370175e8"
                }
            ]
        },
        "production": {
            "kv_namespaces": [
                {
                    "binding": "MY_KV",
                    "id": "a825455ce00f4f7282403da85269f8ea"
                }
            ]
        }
    }
}

[[env.staging.kv_namespaces]]
binding = "MY_KV"
id = "e29b263ab50e42ce9b637fa8370175e8"

[[env.production.kv_namespaces]]
binding = "MY_KV"
id = "a825455ce00f4f7282403da85269f8ea"

To insert a value into a specific KV namespace, you can use:

wrangler kv:key put --env=staging --binding=MY_MV "key" "value"

✨  Success

Since --namespace-id is always unique (unlike binding names), you do not need to specify an --env argument.

Concepts

Most kv commands require you to specify a namespace. A namespace can be specified in two ways:

With a --binding:

   wrangler kv:key get --binding=MY_KV "my key"
   ```

- This can be combined with `--preview` flag to interact with a preview namespace instead of a production namespace.
2. With a `--namespace-id`:

```sh
   wrangler kv:key get --namespace-id=06779da6940b431db6e566b4846d64db "my key"
   ```

Most `kv` subcommands also allow you to specify an environment with the optional `--env` flag. This allows you to publish Workers running the same code but with different namespaces. For example, you could use separate staging and production namespaces for KV data in your Wrangler file:

```jsonc
{
    "$schema": "./node_modules/wrangler/config-schema.json",
    "type": "webpack",
    "name": "my-worker",
    "account_id": "<account id here>",
    "route": "staging.example.com/*",
    "workers_dev": false,
    "kv_namespaces": [
        {
            "binding": "MY_KV",
            "id": "06779da6940b431db6e566b4846d64db"
        }
    ],
    "env": {
        "production": {
            "route": "example.com/*",
            "kv_namespaces": [
                {
                    "binding": "MY_KV",
                    "id": "07bc1f3d1f2a4fd8a45a7e026e2681c6"
                }
            ]
        }
    }
}

"$schema" = "./node_modules/wrangler/config-schema.json"
type = "webpack"
name = "my-worker"
account_id = "<account id here>"
route = "staging.example.com/*"
workers_dev = false

[[kv_namespaces]]
binding = "MY_KV"
id = "06779da6940b431db6e566b4846d64db"

[env.production]
route = "example.com/*"

[[env.production.kv_namespaces]]
  binding = "MY_KV"
  id = "07bc1f3d1f2a4fd8a45a7e026e2681c6"

With the Wrangler file above, you can specify --env production when you want to perform a KV action on the namespace MY_KV under env.production. For example, with the Wrangler file above, you can get a value out of a production KV instance with:

wrangler kv:key get --binding "MY_KV" --env=production "my key"

To learn more about environments, refer to Environments.

`kv:namespace`

`create`

Create a new namespace.

wrangler kv:namespace create $NAME [--env=$ENVIRONMENT_NAME] [--preview]

$NAME
The name of the new namespace.
--env $ENVIRONMENT_NAME optional
If defined, the changes will only apply to the specified environment. Refer to Environments for more information.
--preview optional
Interact with a preview namespace (the preview_id value) instead of production.

Usage

wrangler kv:namespace create "MY_KV"
🌀  Creating namespace with title "worker-MY_KV"
✨  Add the following to your wrangler.toml:
kv_namespaces = [
  { binding = "MY_KV", id = "e29b263ab50e42ce9b637fa8370175e8" }
]

wrangler kv:namespace create "MY_KV" --preview
🌀  Creating namespace with title "my-site-MY_KV_preview"
✨  Success!
Add the following to your wrangler.toml:
kv_namespaces = [
  { binding = "MY_KV", preview_id = "15137f8edf6c09742227e99b08aaf273" }
]

`list`

List all KV namespaces associated with an account ID.

wrangler kv:namespace list

Usage

This example passes the Wrangler command through the jq command:

wrangler kv:namespace list | jq "."
[
  {
    "id": "06779da6940b431db6e566b4846d64db",
    "title": "TEST_NAMESPACE"
  },
  {
    "id": "32ac1b3c2ed34ed3b397268817dea9ea",
    "title": "STATIC_CONTENT"
  }
]

`delete`

Delete a given namespace.

wrangler kv:namespace delete --binding= [--namespace-id=]

--binding required (if no --namespace-id)
The name of the namespace to delete.
--namespace-id required (if no --binding)
The ID of the namespace to delete.
--env $ENVIRONMENT_NAME optional
If defined, the changes will only apply to the specified environment. Refer to Environments for more information.
--preview optional
Interact with a preview namespace instead of production.

Usage

wrangler kv:namespace delete --binding=MY_KV
Are you sure you want to delete namespace f7b02e7fc70443149ac906dd81ec1791? [y/n]
yes
🌀  Deleting namespace f7b02e7fc70443149ac906dd81ec1791
✨  Success

wrangler kv:namespace delete --binding=MY_KV --preview
Are you sure you want to delete namespace 15137f8edf6c09742227e99b08aaf273? [y/n]
yes
🌀  Deleting namespace 15137f8edf6c09742227e99b08aaf273
✨  Success

`kv:key`

`put`

Write a single key-value pair to a particular namespace.

wrangler kv:key put --binding= [--namespace-id=] $KEY $VALUE
✨  Success

$KEY required
The key to write to.
$VALUE required
The value to write.
--binding required (if no --namespace-id)
The name of the namespace to write to.
--namespace-id required (if no --binding)
The ID of the namespace to write to.
--env $ENVIRONMENT_NAME optional
If defined, the changes will only apply to the specified environment. Refer to Environments for more information.
--preview optional
Interact with a preview namespace instead of production. Pass this to the Wrangler file’s kv_namespaces.preview_id instead of kv_namespaces.id.
--ttl optional
The lifetime (in number of seconds) the document should exist before expiring. Must be at least 60 seconds. This option takes precedence over the expiration option.
--expiration optional
The timestamp, in UNIX seconds, indicating when the key-value pair should expire.
--path optional
When defined, Wrangler reads the --path file location to upload its contents as KV documents. This is ideal for security-sensitive operations because it avoids saving keys and values into your terminal history.

Commands (3)·续1

Commands (3)·续1

kv_namespaces

Previewing on Windows Subsystem for Linux (WSL 1/2)

Setting $BROWSER to your browser binary

Setting $BROWSER to wsl-open

route

subdomain

secret

put

delete

list

kv

Getting started

Concepts

kv:namespace

create

Usage

list

Usage

delete

Usage

kv:key

put

Setting $BROWSER to `wsl-open`

`route`

`put`

`delete`

`list`

`kv:namespace`

`create`

`list`

`delete`

`kv:key`

`put`