etcd/etcdctlv3

etcdctl

Commands

PUT [options] <key> <value>

PUT assigns the specified value with the specified key. If key already holds a value, it is overwritten.

Options

• lease -- lease ID (in hexadecimal) to attach to the key.

Return value

Simple reply

• OK if PUT executed correctly. Exit code is zero.

• Error string if PUT failed. Exit code is non-zero.

JSON reply

The JSON encoding of the PUT RPC response.

Protobuf reply

The protobuf encoding of the PUT RPC response.

Examples

./etcdctl PUT foo bar --lease=0x1234abcd
OK
./etcdctl range foo
bar

Notes

If <value> isn't given as command line argument, this command tries to read the value from standard input.

When <value> begins with '-', <value> is interpreted as a flag. Insert '--' for workaround:

./etcdctl put <key> -- <value>
./etcdctl put -- <key> <value>

GET [options] <key> [range_end]

GET gets the key or a range of keys [key, range_end) if range-end is given.

Options

• hex -- print out key and value as hex encode string

• limit -- maximum number of results

• order -- order of results; ASCEND or DESCEND

• sort-by -- sort target; CREATE, KEY, MODIFY, VALUE, or VERSION

TODO: add consistency, from, prefix

Return value

Simple reply

• <key>\n<value>\n<next_key>\n<next_value>...

• Error string if GET failed. Exit code is non-zero.

JSON reply

The JSON encoding of the RPC message for a key-value pair for each fetched key-value.

Protobuf reply

The protobuf encoding of the RPC message for a key-value pair for each fetched key-value.

Examples

./etcdctl get foo
foo
bar

Notes

If any key or value contains non-printable characters or control characters, the output in text format (e.g. simple reply) might be ambiguous. Adding --hex to print key or value as hex encode string in text format can resolve this issue.

DEL [options] <key> [range_end]

Removes the specified key or range of keys [key, range_end) if range-end is given.

Options

TODO: --prefix, --from

Return value

Simple reply

• The number of keys that were removed in decimal if DEL executed correctly. Exit code is zero.

• Error string if DEL failed. Exit code is non-zero.

JSON reply

The JSON encoding of the DeleteRange RPC response.

Protobuf reply

The protobuf encoding of the DeleteRange RPC response.

Examples

./etcdctl put foo bar
OK
./etcdctl del foo
1
./etcdctl range foo

TXN [options]

TXN applies multiple etcd requests as a single atomic transaction. A transaction consists of list of conditions, a list of requests to apply if all the conditions are true, and a list of requests to apply if any condition is false.

Options

• hex -- print out keys and values as hex encoded string

• interactive -- input transaction with interactive mode

Input Format

Interactive mode:

<Txn> ::= <CMP>* "\n" <THEN> "\n" <ELSE> "\n"
<CMP> ::= (<CMPCREATE>|<CMPMOD>|<CMPVAL>|<CMPVER>) "\n"
<CMPOP> ::= "<" | "=" | ">"
<CMPCREATE> := ("c"|"create")"("<KEY>")" <REVISION>
<CMPMOD> ::= ("m"|"mod")"("<KEY>")" <CMPOP> <REVISION>
<CMPVAL> ::= ("val"|"value")"("<KEY>")" <CMPOP> <VALUE>
<CMPVER> ::= ("ver"|"version")"("<KEY>")" <CMPOP> <VERSION>
<THEN> ::= <OP>*
<ELSE> ::= <OP>*
<OP> ::= ((see put, get, del etcdctl command syntax)) "\n"
<KEY> ::= (%q formatted string)
<VALUE> ::= (%q formatted string)
<REVISION> ::= "\""[0-9]+"\""
<VERSION> ::= "\""[0-9]+"\""

TODO: non-interactive mode

Return value

Simple reply

• SUCCESS if etcd processed the transaction success list, FAILURE if etcd processed the transaction failure list.

• Simple reply for each command executed request list, each separated by a blank line.

• Additional error string if TXN failed. Exit code is non-zero.

JSON reply

The JSON encoding of the Txn RPC response.

Protobuf reply

The protobuf encoding of the Txn RPC response.

Examples

./etcdctl txn -i
mod("key1") > "0"

put key1 "overwrote-key1"

put key1 "created-key1"
put key2 "some extra key"

FAILURE

OK

OK

Notes

TODO: non-interactive mode

WATCH [options] [key or prefix]

Watch watches events stream on keys or prefixes. The watch command runs until it encounters an error or is terminated by the user.

Options

• hex -- print out key and value as hex encode string

• interactive -- begins an interactive watch session

• prefix -- watch on a prefix if prefix is set.

• rev -- the revision to start watching. Specifying a revision is useful for observing past events.

Input Format

Input is only accepted for interactive mode.

watch [options] <key or prefix>\n

Return value

Simple reply

• <event>\n<key>\n<value>\n<event>\n<next_key>\n<next_value>\n...

• Additional error string if WATCH failed. Exit code is non-zero.

JSON reply

The JSON encoding of the RPC message for each received Event.

Protobuf reply

The protobuf encoding of the RPC message for each received Event.

Examples

Non-interactive

./etcdctl watch foo
PUT
foo
bar

Interactive

./etcdctl watch -i
watch foo
watch foo
PUT
foo
bar
PUT
foo
bar

Utility Commands

LOCK <lockname>

LOCK acquires a distributed named mutex with a given name. Once the lock is acquired, it will be held until etcdctlv3 is terminated.

Return value

• Once the lock is acquired, the result for the GET on the unique lock holder key is displayed.

• LOCK returns a zero exit code only if it is terminated by a signal and can release the lock.

Example

./etcdctl lock mylock
mylock/1234534535445

MAKE-MIRROR [options] <destination>

make-mirror mirrors a key prefix in an etcd cluster to a destination etcd cluster.

Options

• dest-cacert -- TLS certificate authority file for destination cluster

• dest-cert -- TLS certificate file for destination cluster

• dest-key -- TLS key file for destination cluster

• prefix -- The key-value prefix to mirror

Return value

Simple reply

• The approximate total number of keys transferred to the destination cluster, updated every 30 seconds.

• Error string if mirroring failed. Exit code is non-zero.

Examples

./etcdctl make-mirror mirror.example.com:2379
10
18

Notes

• JSON encoding for keys and values uses base64 since they are byte strings.