etcdctl

The official command-line client for the v3 API. Source: etcdctl/.

Purpose

etcdctl is what every operator types first. It speaks the v3 gRPC API, supports all KV / lease / watch / cluster / auth / maintenance operations, and can drive snapshots, defragmentation, and member changes against a running cluster.

Directory layout

etcdctl/
├── main.go              # calls ctlv3.MustStart
├── ctl.go
├── ctlv3/               # all subcommand implementations
│   ├── ctl.go           # cobra root command, global flags
│   └── command/         # one file per subcommand: get.go, put.go, watch.go, txn.go, lease.go, ...
├── doc/
└── util/

Key subcommands

The complete list is in etcdctl/README.md (a 45 KB doc). Highlights:

Command	What it does
put, get, del	Basic KV operations
watch	Stream key changes
txn	Multi-op atomic transactions
compaction	Discard old revisions
lease grant/revoke/keep-alive/timetolive/list	Lease lifecycle
member add/remove/update/list/promote	Cluster reconfiguration
snapshot save/status/restore	Backup + restore (via etcdutl snapshot package symlinked at etcdctl/ctlv3/command/snapshot_command.go)
defrag	Reclaim free space in bbolt
auth enable/disable/status	Toggle RBAC
user, role	RBAC management
endpoint health/status/hashkv	Per-endpoint diagnostics
alarm list/disarm	Inspect/clear NoSpace + Corrupt alarms
move-leader	Force a leadership transfer
make-mirror	Mirror keyspace to a second cluster (used in disaster-recovery setups)

How it works

1. etcdctl/main.go calls ctlv3.MustStart().
2. ctlv3.MustStart builds the Cobra command tree (one cobra.Command per subcommand under etcdctl/ctlv3/command/).
3. Each subcommand parses its args, constructs a clientv3.Client via client/v3 (using the global --endpoints, --cacert, --cert, --key, --user, --insecure-skip-tls-verify flags), and issues the corresponding gRPC call.
4. Output is formatted by the printer in etcdctl/ctlv3/command/printer.go (text, JSON, protobuf, table, fields).

Integration points

• Imports go.etcd.io/etcd/client/v3 for cluster I/O.
• Imports go.etcd.io/etcd/etcdutl/v3/snapshot for etcdctl snapshot save (the only place where etcdctl reaches into etcdutl's code).
• Imports go.etcd.io/etcd/pkg/v3/cobrautl for shared CLI helpers (error printing, exit codes, version block).

Entry points for modification

• New subcommand → add a file under etcdctl/ctlv3/command/, register it in etcdctl/ctlv3/ctl.go.
• New global flag → etcdctl/ctlv3/ctl.go plus the relevant clientv3.Config field.
• Output formatting → etcdctl/ctlv3/command/printer.go (*printerJSON, *printerSimple, etc.).

Related

• Operator-facing reference: etcdctl/README.md and https://etcd.io/docs/latest/dev-guide/api_reference_v3/.
• See api/ for the underlying gRPC surface.