Cloudflare Docs
KV
Cloudflare Docs
KV
GitHub icon
Edit this page on GitHub
Set theme to dark (⇧+D)
  1. Products
  2. KV
  3. Reference
  4. KV commands

KV commands

​​ kv:namespace

Manage KV namespaces.

The kv:... commands allow you to manage application data in the Cloudflare network to be accessed from Workers using KV.

​​ create

Creates a new KV 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).

​​ create command to create a KV namespace called MY_KV

$ 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" }
]

​​ create command to create a preview KV namespace called MY_KV

$ 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

Lists all KV namespaces associated with the current account ID.

$ wrangler kv:namespace list

​​ Pass the Wrangler command through the jq command

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

​​ delete

Deletes a given KV namespace.

$ wrangler kv:namespace delete [OPTIONS]
  • --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.

​​ Delete a KV namespace called MY_KV

$ 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

​​ Delete a preview KV namespace called MY_KV

$ 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 KV namespace.

​​ put

Writes a single key-value pair to a particular KV namespace.

$ wrangler kv:key put <KEY> [VALUE] [OPTIONS]
  • 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 KV namespace, as stored in the wrangler.toml file, where the key-pair will be stored.
  • --namespace-id string
    • The ID of the KV namespace where the key-pair will be stored.
  • --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.

​​ Put a key-value into the KV namespace with binding name of MY_KV

$ wrangler kv:key put --binding=MY_KV "my-key" "some-value"
Writing the value "some-value" to key "my-key" on namespace f7b02e7fc70443149ac906dd81ec1791.

​​ Put a key-value into the preview KV namespace with binding name of MY_KV

$ wrangler kv:key put --binding=MY_KV --preview "my-key" "some-value"
Writing the value "some-value" to key "my-key" on namespace 15137f8edf6c09742227e99b08aaf273.

​​ Put a key-value into a KV namespace, with a time-to-live value of 10000 seconds

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

​​ Put a key-value into a KV namespace, where the value is read from the value.txt file

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

​​ get

Reads a single value by key from the given KV namespace.

$ wrangler kv:key get <KEY> [OPTIONS]
  • KEY string required
    • The key value to get.
  • --binding string
    • The binding name of the namespace, as stored in the wrangler.toml file, where the key-pair is stored.
  • --namespace-id string
    • The ID of the namespace where the key-pair is stored.
  • --env string optional
    • Perform on a specific environment.
  • --preview boolean optional
    • Interact with a preview namespace instead of production.

​​ Gets the value of the "my-key" key from the KV namespace with binding name MY_KV

$ wrangler kv:key get --binding=MY_KV "my-key"
value

​​ list

Outputs a list of all keys in a given KV namespace.

$ wrangler kv:key list [OPTIONS]
  • --binding string
    • The binding name of the namespace, as stored in the wrangler.toml file, from which keys are listed.
  • --namespace-id string
    • The ID of the namespace from which keys are listed.
  • --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.

​​ Pass the Wrangler command through the jq command

$ wrangler kv:key list --binding=MY_KV --prefix="public" | jq "."
[
  {
    "name": "public_key"
  },
  {
    "name": "public_key_with_expiration",
    "expiration": "2019-09-10T23:18:58Z"
  }
]

​​ delete

Removes a single key value pair from the given namespace.

$ wrangler kv:key delete <KEY> [OPTIONS]
  • KEY string required
    • The key value to get.
  • --binding string
    • The binding name of the namespace, as stored in the wrangler.toml file, from where the key is removed.
  • --namespace-id string
    • The ID of the namespace from which the key is removed.
  • --env string optional
    • Perform on a specific environment.
  • --preview boolean optional
    • Interact with a preview namespace instead of production.

​​ Deletes the key-value pair with key "my-key" from the KV namespace with binding name MY_KV

$ 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 KV namespace in batches.

​​ put

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

$ wrangler kv:bulk put <FILENAME> [OPTIONS]
  • 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, from which key-pairs are bulked.
  • --namespace-id string
    • The ID of the namespace from which key-pairs are bulked.
  • --env string optional
    • Perform on a specific environment.
  • --preview boolean optional
    • Interact with a preview namespace instead of production.

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
  }

]

Here is 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 1024 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.

​​ Writing all the key-value pairs found in the allthethingsupload.json file

$ wrangler kv:bulk put --binding=MY_KV allthethingsupload.json
Success!

​​ delete

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

$ wrangler kv:bulk delete <FILENAME> [OPTIONS]
  • 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, from which keys are removed.
  • --namespace-id string
    • The ID of the namespace from which keys are removed.
  • --env string optional
    • Perform on a specific environment.
  • --preview boolean optional
    • Interact with a preview namespace instead of production.

This command takes a JSON file as an argument containing an array of keys to delete. Here is an example of the JSON input:

["test_key_1", "test_key_2"]

​​ Delete all the keys found in the allthethingsdelete.json file

$ 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!