README.md 5.0 KB
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: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. Releases will follow lockstep with the etcd release cycle.
License
etcdctl is under the Apache 2.0 license. See the LICENSE file for details.