consul/website/source/docs/commands/kv/put.html.markdown.erb

---
layout: "docs"
page_title: "Commands: KV Put"
sidebar_current: "docs-commands-kv-put"
---

# Consul KV Put

Command: `consul kv put`

The `kv put` command writes the data to the given path in the key-value store.
The data can be of any type, but it will be transported as a base64-encoded
string for safe transport. The client will transparently handle the encoding
and decoding of these values.

## Usage

Usage: `consul kv put [options] KEY [DATA]`

#### API Options

<%= partial "docs/commands/http_api_options" %>

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

* `-cas` - Perform a Check-And-Set operation. If this value is specified without
  -modify-index, the key will first be fetched and the resulting ModifyIndex
  will be used on the next query. The default value is false.

* `-flags=<int>` - Unsigned integer value to assign to this key-value 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=<int>` - Unsigned integer representing the ModifyIndex of the
  key. This is often combined with the -cas flag, but it can be specified for
  any key. The default value is 0.

* `-release` - Forfeit the lock on the key at the givne 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=<string>` - User-defined identifer 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
key-value store:

```
$ 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:

```
$ consul kv put redis/config/connections
Success! Data written to: redis/config/connections
```

!> **Be careful when overwriting data!** The above operation would overwrite
the value at the key to the empty value.

For longer or sensitive values, it is possible to read from a file by prefixing
with the `@` symbol:

```
$ consul kv put redis/config/password @password.txt
Success! Data written to: redis/config/connections
```

Or read values from stdin by specifying the `-` symbol:

```
$ echo "5" | consul kv put redis/config/password -
Success! Data written to: redis/config/connections

$ consul kv put redis/config/password -
5
<CTRL+D>
Success! Data written to: redis/config/connections
```

~> 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 secure values in Consul's KV store, Vault provides a
more robust interface for secret management.

To only update a key if it has not been modified since a given index, specify
the `-cas` and `-modify-index` flags:

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

It is also possible to have Consul fetch the current ModifyIndex before making
the query, by omitting the `-modify-index` flag. If the data is changed between
the initial read and the write, the operation will fail.

```
$ consul kv put -cas redis/config/connections 10
Success! Data written to: redis/config/connections
```

To specify flags on the key, use the `-flags` option. These flags are completely
controlled by the user:

```
$ consul kv put -flags=42 redis/config/password s3cr3t
Success! Data written to: redis/config/password
```

To create or tune a lock, use the `-acquire` and `-session` flags. Note that the session must already exist (this command will not create it or manage it):

```
$ consul kv put -acquire -session=abc123 redis/lock/update
Success! Lock acquired on: redis/lock/update
```

When you are finished, release the lock:

```
$ 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 [<tt>consul
lock</tt>](/docs/commands/lock.html) command. It provides higher-level
functionality without exposing the internal APIs of Consul.