--- layout: commands page_title: 'Commands: KV Put' --- # Consul KV Put Command: `consul kv put` The `kv put` command writes the data to the given path in the KV store. -> When writing multiple entries at once, consider using [`kv import`](/commands/kv/import) instead. Alternatively, the [transaction API](/api-docs/txn) provides support for performing up to 64 KV operations atomically. ## Usage Usage: `consul kv put [options] KEY [DATA]` #### API Options @include 'http_api_options_client.mdx' @include 'http_api_options_server.mdx' #### Enterprise Options @include 'http_api_namespace_options.mdx' @include 'http_api_partition_options.mdx' #### KV Put Options - `-acquire` - Obtain a lock on the key. If the key does not exist, this operation will create the key and obtain the lock. The session must already exist and be specified via the -session flag. The default value is false. - `-base64` - Treat the data as base 64 encoded. The default value is false. - `-cas` - Perform a Check-And-Set operation. Specifying this value also requires the -modify-index flag to be set. The default value is false. - `-flags=` - Unsigned integer value to assign to this KV pair. This value is not read by Consul, so clients can use this value however makes sense for their use case. The default value is 0 (no flags). - `-modify-index=` - Unsigned integer representing the ModifyIndex of the key. This is used in combination with the -cas flag. - `-release` - Forfeit the lock on the key at the given path. This requires the -session flag to be set. The key must be held by the session in order to be unlocked. The default value is false. - `-session=` - User-defined identifier for this session as a string. This is commonly used with the -acquire and -release operations to build robust locking, but it can be set on any key. The default value is empty (no session). ## Examples To insert a value of "5" for the key named "redis/config/connections" in the KV store: ```shell-session hideClipboard $ consul kv put redis/config/connections 5 Success! Data written to: redis/config/connections ``` If no data is specified, the key will be created with empty data: ```shell-session hideClipboard $ consul kv put redis/config/connections Success! Data written to: redis/config/connections ``` !> **Be careful of overwriting data!** The above operation would overwrite any existing value at the key to the empty value. ### Base64 Encoded Values If the `-base64` flag is set, the given data will be Base64-decoded before writing: ```shell-session hideClipboard $ consul kv put -base64 foo/encoded aGVsbG8gd29ybGQK Success! Data written to: foo/encoded ``` ### Longer or Sensitive Values For longer or sensitive values, it is possible to read from a file by supplying its path prefixed with the `@` symbol: ```shell-session hideClipboard $ consul kv put redis/config/password @password.txt Success! Data written to: redis/config/password ``` Or read values from stdin by specifying the `-` symbol: ```shell-session hideClipboard $ echo "5" | consul kv put redis/config/connections - Success! Data written to: redis/config/connections ``` ```shell-session hideClipboard $ consul kv put redis/config/connections - 5 Success! Data written to: redis/config/connections ``` ```shell-session hideClipboard $ consul kv put leaderboard/scores - < For secret and sensitive values, you should consider using a secret management solution like **[HashiCorp's Vault](https://www.vaultproject.io/)**. While it is possible to encrpyt data before writing it to Consul's KV store, Consul provides no built-in support for encryption at-rest. ### Atomic Check-And-Set (CAS) To only update a key if it has not been modified since a given index, specify the `-cas` and `-modify-index` flags: ```shell-session hideClipboard $ consul kv get -detailed redis/config/connections | grep ModifyIndex ModifyIndex 456 $ consul kv put -cas -modify-index=123 redis/config/connections 10 Error! Did not write to redis/config/connections: CAS failed $ consul kv put -cas -modify-index=456 redis/config/connections 10 Success! Data written to: redis/config/connections ``` ### Locking Primatives To create or tune a lock, use the `-acquire` and `-session` flags. The session must already exist (this command will not create it or manage it): ```shell-session hideClipboard $ consul kv put -acquire -session=abc123 redis/lock/update Success! Lock acquired on: redis/lock/update ``` When you are finished, release the lock: ```shell-session hideClipboard $ consul kv put -release -session=acb123 redis/lock/update Success! Lock released on: redis/lock/update ``` ~> **Warning!** If you are trying to build a locking mechanism with these low-level primitives, you may want to look at the [consul lock](/commands/lock) command. It provides higher-level functionality without exposing the internal APIs of Consul. ### Flags To set user-defined flags on the entry, use the `-flags` option. These flags are completely controlled by the user and have no special meaning to Consul: ```shell-session hideClipboard $ consul kv put -flags=42 redis/config/password s3cr3t Success! Data written to: redis/config/password ```