cli reference

the phalanx binary — a lightweight client for interacting with a running cluster.

install

go build -ldflags="-s -w" -o phalanx ./cmd/phalanx

phalanx put

Write a key-value pair to the cluster via the KV.Propose RPC.

phalanx put <key> <value> [-addr host:port]

$ phalanx put config.ttl 3600 -addr 127.0.0.1:9000
✓ SET config.ttl = 3600

The command blocks until the entry is committed to a majority of the cluster. Default timeout is 5 seconds.

phalanx get

Read a value by key via the KV.Read RPC. Linearizable — the leader verifies it still holds a majority lease before responding.

phalanx get <key> [-addr host:port]

$ phalanx get config.ttl -addr 127.0.0.1:9000
config.ttl = 3600

$ phalanx get nonexistent -addr 127.0.0.1:9000
(not found) nonexistent

phalanx status

Query the debug HTTP endpoint and display a formatted table of the node's health, Raft state, and metrics.

phalanx status [-addr host:port]

$ phalanx status -addr 127.0.0.1:8080
┌──────────────────────────────────────────────────┐
│                  NODE STATUS                     │
├──────────────────────────────────────────────────┤
│ Node ID                                  node-0 │
│ State                                    LEADER │
│ Term                                          3 │
│ Leader                                   node-0 │
│ Commit Index                                 42 │
│ Applied Index                                42 │
│ Log Length                                   43 │
│ KV Size                                      15 │
│ Peers                        node-1, node-2     │
│                                                  │
│                    METRICS                       │
├──────────────────────────────────────────────────┤
│ Messages Sent                              1247 │
│ Elections                                     1 │
│ Proposals                                    15 │
│ Reads                                         8 │
└──────────────────────────────────────────────────┘

note: put and get connect to the gRPC port (default 9000).status connects to the HTTP debug port (default 8080).

leader redirection

If you send a request to a follower, the response includes the leader's address:

$ phalanx put foo bar -addr 127.0.0.1:9001
✗ failed: not leader (try: -addr 127.0.0.1:9000)

The CLI does not auto-redirect. This is intentional — the operator should know which node is the leader and can use the hint to retry.

default addresses