etcd-io__etcd/etcdctl

etcdctl

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

Getting etcdctl

The latest release is available as a binary at Github along with etcd.

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

Directories can also have a trailing / added to output using -p.

$ etcdctl ls -p
/akey
/adir/

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_WATCH_VALUE=My configuration stuff
ETCD_WATCH_MODIFIED_INDEX=1999
ETCD_WATCH_KEY=/foo/bar
ETCD_WATCH_ACTION=set
ETCD_WATCH_VALUE=My new configuration stuff
ETCD_WATCH_MODIFIED_INDEX=2000
ETCD_WATCH_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_WATCH_VALUE=My configuration stuff
ETCD_WATCH_MODIFIED_INDEX=1999
ETCD_WATCH_KEY=/foo/bar
ETCD_WATCH_ACTION=set
ETCD_WATCH_VALUE=My new configuration stuff
ETCD_WATCH_MODIFIED_INDEX=2000
ETCD_WATCH_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:2379 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. Releases will follow lockstep with the etcd release cycle.

License

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