etcd/etcdctl/README.md

etcdctl
========

`etcdctl` is a command line client for [etcd][etcd].
It can be used in scripts or for administrators to explore an etcd cluster.

[etcd]: https://github.com/coreos/etcd


## Getting etcdctl

The latest release is available as a binary at [Github][github-release] along with etcd.

[github-release]: https://github.com/coreos/etcd/releases/

You can also build etcdctl from source using the build script found in the parent directory.

## Usage

### Setting Key Values

Set a value on the `/foo/bar` key:

```
$ etcdctl set /foo/bar "Hello world"
Hello world
```

Set a value on the `/foo/bar` key with a value that expires in 60 seconds:

```
$ etcdctl set /foo/bar "Hello world" --ttl 60
Hello world
```

Conditionally set a value on `/foo/bar` if the previous value was "Hello world":

```
$ etcdctl set /foo/bar "Goodbye world" --swap-with-value "Hello world"
Goodbye world
```

Conditionally set a value on `/foo/bar` if the previous etcd index was 12:

```
$ etcdctl set /foo/bar "Goodbye world" --swap-with-index 12
Goodbye world
```

Create a new key `/foo/bar`, only if the key did not previously exist:

```
$ etcdctl mk /foo/new_bar "Hello world"
Hello world
```

Create a new dir `/fooDir`, only if the key did not previously exist:

```
$ etcdctl mkdir /fooDir
```

Update an existing key `/foo/bar`, only if the key already existed:

```
$ etcdctl update /foo/bar "Hola mundo"
Hola mundo
```

Create or update a directory called `/mydir`:

```
$ etcdctl setDir /mydir
```


### Retrieving a key value

Get the current value for a single key in the local etcd node:

```
$ etcdctl get /foo/bar
Hello world
```

Get the current value for a key within the cluster:

```
$ etcdctl get /foo/bar --consistent
Hello world
```

Get the value of a key with additional metadata in a parseable format:

```
$ etcdctl -o extended get /foo/bar
Key: /foo/bar
Modified-Index: 72
TTL: 0
Etcd-Index: 72
Raft-Index: 5611
Raft-Term: 1

Hello World
```

### Listing a directory

Explore the keyspace using the `ls` command

```
$ etcdctl ls
/akey
/adir
$ etcdctl ls /adir
/adir/key1
/adir/key2
```

Add `--recursive` to recursively list subdirectories encountered.

```
$ etcdctl ls --recursive
/akey
/adir
/adir/key1
/adir/key2
```


### Deleting a key

Delete a key:

```
$ etcdctl rm /foo/bar
```

Delete an empty directory or a key-value pair

```
$ etcdctl rmdir /path/to/dir
```

or

```
$ etcdctl rm /path/to/dir --dir
```

Recursively delete a key and all child keys:

```
$ etcdctl rm /path/to/dir --recursive
```

Conditionally delete `/foo/bar` if the previous value was "Hello world":

```
$ etcdctl rm /foo/bar --with-value "Hello world"
```

Conditionally delete `/foo/bar` if the previous etcd index was 12:

```
$ etcdctl rm /foo/bar --with-index 12
```

### Watching for changes

Watch for only the next change on a key:

```
$ etcdctl watch /foo/bar
Hello world
```

Continuously watch a key:

```
$ etcdctl watch /foo/bar --forever
Hello world
.... client hangs forever until ctrl+C printing values as key change
```

Continuously watch a key, starting with a given etcd index:

```
$ etcdctl watch /foo/bar --forever --index 12
Hello world
.... client hangs forever until ctrl+C printing values as key change
```

Continuously watch a key and exec a program:

```
$ etcdctl exec-watch /foo/bar -- sh -c "env | grep ETCD"
ETCD_WATCH_ACTION=set
ETCD_VALUE=My configuration stuff
ETCD_MODIFIED_INDEX=1999
ETCD_KEY=/foo/bar
ETCD_WATCH_ACTION=set
ETCD_VALUE=My new configuration stuff
ETCD_MODIFIED_INDEX=2000
ETCD_KEY=/foo/bar
```

Continuously and recursively watch a key and exec a program:
```
$ etcdctl exec-watch --recursive /foo -- sh -c "env | grep ETCD"
ETCD_WATCH_ACTION=set
ETCD_VALUE=My configuration stuff
ETCD_MODIFIED_INDEX=1999
ETCD_KEY=/foo/bar
ETCD_WATCH_ACTION=set
ETCD_VALUE=My new configuration stuff
ETCD_MODIFIED_INDEX=2000
ETCD_KEY=/foo/barbar
```

## Return Codes

The following exit codes can be returned from etcdctl:

```
0    Success
1    Malformed etcdctl arguments
2    Failed to connect to host
3    Failed to auth (client cert rejected, ca validation failure, etc)
4    400 error from etcd
5    500 error from etcd
```

## Peers

If your etcd cluster isn't available on `http://127.0.0.1:4001` you can specify
a `--peers` flag or `ETCDCTL_PEERS` environment variable. You can list one peer,
or a comma-separated list of peers.

```
ETCDCTL_PEERS="http://10.0.28.1:4002" etcdctl set my-key to-a-value
ETCDCTL_PEERS="http://10.0.28.1:4002,http://10.0.28.2:4002,http://10.0.28.3:4002" etcdctl set my-key to-a-value
etcdctl --peers http://10.0.28.1:4002 my-key to-a-value
etcdctl --peers http://10.0.28.1:4002,http://10.0.28.2:4002,http://10.0.28.3:4002 etcdctl set my-key to-a-value
```

## Project Details

### Versioning

etcdctl uses [semantic versioning][semver].
Releases will follow lockstep with the etcd release cycle.

[semver]: http://semver.org/

### License

etcdctl is under the Apache 2.0 license. See the [LICENSE][license] file for details.

[license]: https://github.com/coreos/etcdctl/blob/master/LICENSE