---
title: Wrangler KV commands · Cloudflare Workers KV docs
description: Manage Workers KV namespaces.
lastUpdated: 2024-09-05T08:56:02.000Z
source_url:
  html: https://b37efaf9.preview.developers.cloudflare.com/kv/reference/kv-commands/index.md
  md: https://b37efaf9.preview.developers.cloudflare.com/kv/reference/kv-commands/
---

## `kv namespace`

Manage Workers KV namespaces.

Note

The `kv ...` commands allow you to manage your Workers KV resources in the Cloudflare network. Learn more about using Workers KV with Wrangler in the [Workers KV guide](https://developers.cloudflare.com/kv/get-started/).

Warning

Since version 3.60.0, Wrangler supports the `kv ...` syntax. If you are using versions below 3.60.0, the command follows the `kv:...` syntax. Learn more about the deprecation of the `kv:...` syntax in the [Wrangler commands](https://developers.cloudflare.com/kv/reference/kv-commands/#deprecations) for KV page.

### `create`

Create a new namespace.

```txt
wrangler kv namespace create <NAMESPACE> [OPTIONS]
```

* `NAMESPACE` string required
  * The name of the new namespace.
* `--env` string optional
  * Perform on a specific environment.
* `--preview` boolean optional
  * Interact with a preview namespace (the `preview_id` value).

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://developers.cloudflare.com/workers/wrangler/configuration/).
* `--cwd` string
  * Run as if Wrangler was started in the specified directory instead of the current working directory.

The following is an example of using the `create` command to create a KV namespace called `MY_KV`.

```sh
npx wrangler kv namespace create "MY_KV"
```

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

The following is an example of using the `create` command to create a preview KV namespace called `MY_KV`.

```sh
npx wrangler kv namespace create "MY_KV" --preview
```

```sh
🌀 Creating namespace with title "my-site-MY_KV_preview"
✨ Success!
Add the following to your configuration file in your kv_namespaces array:
kv_namespaces = [
  { binding = "MY_KV", preview_id = "15137f8edf6c09742227e99b08aaf273" }
]
```

### `list`

List all KV namespaces associated with the current account ID.

```txt
wrangler kv namespace list
```

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://developers.cloudflare.com/workers/wrangler/configuration/).
* `--cwd` string
  * Run as if Wrangler was started in the specified directory instead of the current working directory.

The following is an example that passes the Wrangler command through the `jq` command:

```sh
npx wrangler kv namespace list | jq "."
```

```sh
[
  {
    "id": "06779da6940b431db6e566b4846d64db",
    "title": "TEST_NAMESPACE"
  },
  {
    "id": "32ac1b3c2ed34ed3b397268817dea9ea",
    "title": "STATIC_CONTENT"
  }
]
```

### `delete`

Delete a given namespace.

```txt
wrangler kv namespace delete {--binding=<BINDING>|--namespace-id=<NAMESPACE_ID>} [OPTIONS]
```

Warning

This command requires `--binding` or `--namespace-id`.

* `--binding` string
  * The binding name of the namespace, as stored in the Wrangler file, to delete.
* `--namespace-id` string
  * The ID of the namespace to delete.
* `--env` string optional
  * Perform on a specific environment.
* `--preview` boolean optional
  * Interact with a preview namespace instead of production.

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://developers.cloudflare.com/workers/wrangler/configuration/).
* `--cwd` string
  * Run as if Wrangler was started in the specified directory instead of the current working directory.

The following is an example of deleting a KV namespace called `MY_KV.`

```sh
npx wrangler kv namespace delete --binding=MY_KV
```

```sh
Are you sure you want to delete namespace f7b02e7fc70443149ac906dd81ec1791? [y/n]
yes
Deleting namespace f7b02e7fc70443149ac906dd81ec1791
Deleted namespace f7b02e7fc70443149ac906dd81ec1791
```

The following is an example of deleting a preview KV namespace called `MY_KV`.

```sh
npx wrangler kv namespace delete --binding=MY_KV --preview
```

```sh
Are you sure you want to delete namespace 15137f8edf6c09742227e99b08aaf273? [y/n]
yes
Deleting namespace 15137f8edf6c09742227e99b08aaf273
Deleted namespace 15137f8edf6c09742227e99b08aaf273
```

## `kv key`

Manage key-value pairs within a Workers KV namespace.

Note

The `kv ...` commands allow you to manage your Workers KV resources in the Cloudflare network. Learn more about using Workers KV with Wrangler in the [Workers KV guide](https://developers.cloudflare.com/kv/get-started/).

Warning

Since version 3.60.0, Wrangler supports the `kv ...` syntax. If you are using versions below 3.60.0, the command follows the `kv:...` syntax. Learn more about the deprecation of the `kv:...` syntax in the [Wrangler commands](https://developers.cloudflare.com/kv/reference/kv-commands/) for KV page.

### `put`

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

```txt
wrangler kv key put <KEY> {<VALUE>|--path=<PATH>} {--binding=<BINDING>|--namespace-id=<NAMESPACE_ID>} [OPTIONS]
```

Warning

This command requires a `VALUE` or `--path`.\
This command requires a `--binding` or `--namespace-id` flag.

* `KEY` string required
  * The key to write to.
* `VALUE` string optional
  * The value to write.
* `--path` optional
  * When defined, the value is loaded from the file at `--path` rather than reading it from the `VALUE` argument. This is ideal for security-sensitive operations because it avoids saving keys and values into your terminal history.
* `--binding` string
  * The binding name of the namespace, as stored in the Wrangler file, to write to.
* `--namespace-id` string
  * The ID of the namespace to write to.
* `--env` string optional
  * Perform on a specific environment.
* `--preview` boolean optional
  * Interact with a preview namespace instead of production.
* `--ttl` number optional
  * The lifetime (in number of seconds) that the key-value pair should exist before expiring. Must be at least `60` seconds. This option takes precedence over the `expiration` option.
* `--expiration` number optional
  * The timestamp, in UNIX seconds, indicating when the key-value pair should expire.
* `--metadata` string optional
  * Any (escaped) JSON serialized arbitrary object to a maximum of 1024 bytes.
* `--local` boolean (default: true) optional
  * Interact with locally persisted data.
* `--remote` boolean (default: false) optional
  * Interact with remote storage.
* `--persist-to` string optional
  * Specify directory for locally persisted data.

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://developers.cloudflare.com/workers/wrangler/configuration/).
* `--cwd` string
  * Run as if Wrangler was started in the specified directory instead of the current working directory.

The following is an example that puts a key-value into the namespace with binding name of `MY_KV`.

```sh
npx wrangler kv key put --binding=MY_KV "my-key" "some-value"
```

```sh
Writing the value "some-value" to key "my-key" on namespace f7b02e7fc70443149ac906dd81ec1791.
```

The following is an example that puts a key-value into the preview namespace with binding name of `MY_KV`.

```sh
npx wrangler kv key put --binding=MY_KV --preview "my-key" "some-value"
```

```sh
Writing the value "some-value" to key "my-key" on namespace 15137f8edf6c09742227e99b08aaf273.
```

The following is an example that puts a key-value into a namespace, with a time-to-live value of `10000` seconds.

```sh
npx wrangler kv key put --binding=MY_KV "my-key" "some-value" --ttl=10000
```

```sh
Writing the value "some-value" to key "my-key" on namespace f7b02e7fc70443149ac906dd81ec1791.
```

The following is an example that puts a key-value into a namespace, where the value is read from the `value.txt` file.

```sh
npx wrangler kv key put --binding=MY_KV "my-key" --path=value.txt
```

```sh
Writing the contents of value.txt to the key "my-key" on namespace f7b02e7fc70443149ac906dd81ec1791.
```

### `list`

Output a list of all keys in a given namespace.

```txt
wrangler kv key list {--binding=<BINDING>|--namespace-id=<NAMESPACE_ID>} [OPTIONS]
```

Warning

This command requires `--binding` or `--namespace-id`.

* `--binding` string
  * The binding name of the namespace, as stored in the Wrangler file, to list from.
* `--namespace-id` string
  * The ID of the namespace to list from.
* `--env` string optional
  * Perform on a specific environment.
* `--preview` boolean optional
  * Interact with a preview namespace instead of production.
* `--prefix` string optional
  * Only list keys that begin with the given prefix.
* `--local` boolean (default: true) optional
  * Interact with locally persisted data.
* `--remote` boolean (default: false) optional
  * Interact with remote storage.
* `--persist-to` string optional
  * Specify directory for locally persisted data.

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://developers.cloudflare.com/workers/wrangler/configuration/).
* `--cwd` string
  * Run as if Wrangler was started in the specified directory instead of the current working directory.

Below is an example that passes the Wrangler command through the `jq` command:

```sh
npx wrangler kv key list --binding=MY_KV --prefix="public" | jq "."
```

```sh
[
  {
    "name": "public_key"
  },
  {
    "name": "public_key_with_expiration",
    "expiration": "2019-09-10T23:18:58Z"
  }
]
```

### `get`

Read a single value by key from the given namespace.

```txt
wrangler kv key get <KEY> {--binding=<BINDING>|--namespace-id=<NAMESPACE_ID>} [OPTIONS]
```

Warning

Exactly one of `--binding` or `--namespace-id` is required.

* `KEY` string required
  * The key value to get.
* `--binding` string
  * The binding name of the namespace, as stored in the Wrangler file, to get from.
* `--namespace-id` string
  * The ID of the namespace to get from.
* `--env` string optional
  * Perform on a specific environment.
* `--preview` boolean optional
  * Interact with a preview namespace instead of production.
* `--text` boolean optional
  * Decode the returned value as a UTF-8 string.
* `--local` boolean (default: true) optional
  * Interact with locally persisted data.
* `--remote` boolean (default: false) optional
  * Interact with remote storage.
* `--persist-to` string optional
  * Specify directory for locally persisted data.

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://developers.cloudflare.com/workers/wrangler/configuration/).
* `--cwd` string
  * Run as if Wrangler was started in the specified directory instead of the current working directory.

The following is an example that gets the value of the `"my-key"` key from the KV namespace with binding name `MY_KV`.

```sh
npx wrangler kv key get --binding=MY_KV "my-key"
```

```sh
value
```

### `delete`

Remove a single key value pair from the given namespace.

```txt
wrangler kv key delete <KEY> {--binding=<BINDING>|--namespace-id=<NAMESPACE_ID>} [OPTIONS]
```

Warning

Exactly one of `--binding` or `--namespace-id` is required.

* `KEY` string required
  * The key value to get.
* `--binding` string
  * The binding name of the namespace, as stored in the Wrangler file, to delete from.
* `--namespace-id` string
  * The ID of the namespace to delete from.
* `--env` string optional
  * Perform on a specific environment.
* `--preview` boolean optional
  * Interact with a preview namespace instead of production.
* `--local` boolean (default: true) optional
  * Interact with locally persisted data.
* `--remote` boolean (default: false) optional
  * Interact with remote storage.
* `--persist-to` string optional
  * Specify directory for locally persisted data.

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://developers.cloudflare.com/workers/wrangler/configuration/).
* `--cwd` string
  * Run as if Wrangler was started in the specified directory instead of the current working directory.

The following is an example that deletes the key-value pair with key `"my-key"` from the KV namespace with binding name `MY_KV`.

```sh
npx wrangler kv key delete --binding=MY_KV "my-key"
```

```sh
Deleting the key "my-key" on namespace f7b02e7fc70443149ac906dd81ec1791.
```

## `kv bulk`

Manage multiple key-value pairs within a Workers KV namespace in batches.

Note

The `kv ...` commands allow you to manage your Workers KV resources in the Cloudflare network. Learn more about using Workers KV with Wrangler in the [Workers KV guide](https://developers.cloudflare.com/kv/get-started/).

Warning

Since version 3.60.0, Wrangler supports the `kv ...` syntax. If you are using versions below 3.60.0, the command follows the `kv:...` syntax. Learn more about the deprecation of the `kv:...` syntax in the [Wrangler commands](https://developers.cloudflare.com/kv/reference/kv-commands/) for KV page.

### `put`

Write a JSON file containing an array of key-value pairs to the given namespace.

```txt
wrangler kv bulk put <FILENAME> {--binding=<BINDING>|--namespace-id=<NAMESPACE_ID>} [OPTIONS]
```

Warning

This command requires `--binding` or `--namespace-id`.

* `FILENAME` string required
  * The JSON file containing an array of key-value pairs to write to the namespace.
* `--binding` string
  * The binding name of the namespace, as stored in the Wrangler file, to write to.
* `--namespace-id` string
  * The ID of the namespace to write to.
* `--env` string optional
  * Perform on a specific environment.
* `--preview` boolean optional
  * Interact with a preview namespace instead of production.
* `--local` boolean (default: true) optional
  * Interact with locally persisted data.
* `--remote` boolean (default: false) optional
  * Interact with remote storage.
* `--persist-to` string optional
  * Specify directory for locally persisted data.

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://developers.cloudflare.com/workers/wrangler/configuration/).
* `--cwd` string
  * Run as if Wrangler was started in the specified directory instead of the current working directory.

This command takes a JSON file as an argument with a list of key-value pairs to upload. An example of JSON input:

```json
[
  {
    "key": "test_key",
    "value": "test_value",
    "expiration_ttl": 3600
  }
]
```

KV namespace values can only store strings. In order to save complex a value, stringify it to JSON:

```json
[
  {
    "key": "test_key",
    "value": "{\"name\": \"test_value\"}",
    "expiration_ttl": 3600
  }
]
```

Refer to the full schema for key-value entries uploaded via the bulk API:

* `key` string required
  * The key’s name. The name may be 512 bytes maximum. All printable, non-whitespace characters are valid.
* `value` string required
  * The UTF-8 encoded string to be stored, up to 25 MB in length.
* `metadata` object optional
  * Any arbitrary object (must serialize to JSON) to a maximum of 1,024 bytes.
* `expiration` number optional
  * The time, measured in number of seconds since the UNIX epoch, at which the key should expire.
* `expiration_ttl` number optional
  * The number of seconds the document should exist before expiring. Must be at least `60` seconds.
* `base64` boolean optional
  * When true, the server will decode the value as base64 before storing it. This is useful for writing values that would otherwise be invalid JSON strings, such as images. Defaults to `false`.

Note

If both `expiration` and `expiration_ttl` are specified for a given key, the API will prefer `expiration_ttl`.

The following is an example of writing all the key-value pairs found in the `allthethingsupload.json` file.

```sh
npx wrangler kv bulk put --binding=MY_KV allthethingsupload.json
```

```sh
Success!
```

### `delete`

Delete all keys read from a JSON file within a given namespace.

```txt
wrangler kv bulk delete <FILENAME> {--binding=<BINDING>|--namespace-id=<NAMESPACE_ID>} [OPTIONS]
```

Warning

This command requires `--binding` or `--namespace-id`.

* `FILENAME` string required
  * The JSON file containing an array of keys to delete from the namespace.
* `--binding` string
  * The binding name of the namespace, as stored in the Wrangler file, to delete from.
* `--namespace-id` string
  * The ID of the namespace to delete from.
* `--env` string optional
  * Perform on a specific environment.
* `--preview` boolean optional
  * Interact with a preview namespace instead of production.
* `--local` boolean (default: true) optional
  * Interact with locally persisted data.
* `--remote` boolean (default: false) optional
  * Interact with remote storage.
* `--persist-to` string optional
  * Specify directory for locally persisted data.

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://developers.cloudflare.com/workers/wrangler/configuration/).
* `--cwd` string
  * Run as if Wrangler was started in the specified directory instead of the current working directory.

This command takes a JSON file as an argument containing the keys to delete.

The following is an example of the JSON input:

```json
["test_key_1", "test_key_2"]
```

The command also accepts keys in the format output from `wrangler kv key list`:

```json
[{ "name": "test_key_1" }, { "name": "test_key_2" }]
```

The following is an example of deleting all the keys found in the `allthethingsdelete.json` file.

```sh
npx wrangler kv bulk delete --binding=MY_KV allthethingsdelete.json
```

```sh
? Are you sure you want to delete all keys in allthethingsdelete.json from kv-namespace with id "f7b02e7fc70443149ac906dd81ec1791"? › (Y/n)
Success!
```

## Deprecations

Below are deprecations to Wrangler commands for Workers KV.

### `kv:...` syntax deprecation

Since version 3.60.0, Wrangler supports the `kv ...` syntax. If you are using versions below 3.60.0, the command follows the `kv:...` syntax.

The `kv:...` syntax is deprecated in versions 3.60.0 and beyond and will be removed in a future major version.

For example, commands using the `kv ...` syntax look as such:

```sh
wrangler kv namespace list
wrangler kv key get <KEY>
wrangler kv bulk put <FILENAME>
```

The same commands using the `kv:...` syntax look as such:

```sh
wrangler kv:namespace list
wrangler kv:key get <KEY>
wrangler kv:bulk put <FILENAME>
```
