etcdctl: Usage, Options & Common CI Errors

etcdctl reads and writes keys in an etcd cluster from the shell.

etcdctl seeds and inspects coordination state in CI. The most common surprise is API versioning: v2 and v3 commands differ, and the wrong ETCDCTL_API gives confusing "no such command" errors.

What it does

etcdctl is the command-line client for etcd, a distributed key-value store. With the v3 API it does put/get/del, watch, lease, and member operations against one or more endpoints over gRPC (TLS by default in secured clusters).

Common usage

Terminal

ETCDCTL_API=3 etcdctl --endpoints=http://localhost:2379 put /k v
ETCDCTL_API=3 etcdctl --endpoints=http://localhost:2379 get /k
ETCDCTL_API=3 etcdctl --endpoints=http://localhost:2379 endpoint health
ETCDCTL_API=3 etcdctl --endpoints=https://db:2379 --cacert=ca.crt --cert=c.crt --key=c.key get / --prefix

Options

Flag / env	What it does
ETCDCTL_API=3	Select the v3 API (env var)
--endpoints <urls>	Comma-separated server endpoints
put / get / del	Write / read / delete a key
get <prefix> --prefix	Read all keys under a prefix
--cacert/--cert/--key	TLS certificate paths
endpoint health	Report cluster health

Common errors in CI

Error: ... context deadline exceeded - etcd is unreachable or still starting; check --endpoints and gate on etcdctl endpoint health. "No help topic for 'put'" or v2-style output means ETCDCTL_API is unset/2 - export ETCDCTL_API=3 (older etcdctl defaults to v2; v3.4+ defaults to v3). "transport: authentication handshake failed: x509" means the cluster needs --cacert/--cert/--key for the https endpoints.