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

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 for KV page.

create

Create a new namespace.

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

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

npx wrangler kv namespace create "MY_KV"

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

npx wrangler kv namespace create "MY_KV" --preview

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

wrangler kv namespace list

The following global flags work on every command:

• --help boolean
  • Show help.
• --version boolean
  • Show version number.
• --config string (not supported by Pages)
  • Path to .toml configuration file.

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

npx 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=<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.toml 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.
• --version boolean
  • Show version number.
• --config string (not supported by Pages)
  • Path to .toml configuration file.

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

npx wrangler kv namespace delete --binding=MY_KV

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.

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

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.

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 for KV page.

put

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

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.toml 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 optional
  • Interact with locally persisted data.
• --persist-to string optional
  • Specify directory for locally persisted data.

The following global flags work on every command:

• --help boolean
  • Show help.
• --version boolean
  • Show version number.
• --config string (not supported by Pages)
  • Path to .toml configuration file.

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

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

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.

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

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.

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

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.

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

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.

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.toml 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 optional
  • Interact with locally persisted data.
• --persist-to string optional
  • Specify directory for locally persisted data.

The following global flags work on every command:

• --help boolean
  • Show help.
• --version boolean
  • Show version number.
• --config string (not supported by Pages)
  • Path to .toml configuration file.

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

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

[
  {
    "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.

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.toml 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 optional
  • Interact with locally persisted data.
• --persist-to string optional
  • Specify directory for locally persisted data.

The following global flags work on every command:

• --help boolean
  • Show help.
• --version boolean
  • Show version number.
• --config string (not supported by Pages)
  • Path to .toml configuration file.

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

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

value

delete

Remove a single key value pair from the given namespace.

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.toml 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 optional
  • Interact with locally persisted data.
• --persist-to string optional
  • Specify directory for locally persisted data.

The following global flags work on every command:

• --help boolean
  • Show help.
• --version boolean
  • Show version number.
• --config string (not supported by Pages)
  • Path to .toml configuration file.

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

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

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.

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 for KV page.

put

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

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.toml 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 optional
  • Interact with locally persisted data.
• --persist-to string optional
  • Specify directory for locally persisted data.

The following global flags work on every command:

• --help boolean
  • Show help.
• --version boolean
  • Show version number.
• --config string (not supported by Pages)
  • Path to .toml configuration file.

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

[
  {
    "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:

[
  {
    "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.

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

Success!

delete

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

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.toml 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 optional
  • Interact with locally persisted data.
• --persist-to string optional
  • Specify directory for locally persisted data.

The following global flags work on every command:

• --help boolean
  • Show help.
• --version boolean
  • Show version number.
• --config string (not supported by Pages)
  • Path to .toml configuration file.

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

The following is an example of the JSON input:

["test_key_1", "test_key_2"]

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

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

? 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:

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

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

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

Was this helpful?

What did you like?

Accurate

Easy to understand

Solved my problem

Helped me decide to use the product

Other

What went wrong?

Hard to understand

Incorrect information

Missing the information

Other

Thank you for helping improve Cloudflare's documentation!