Command line

Command line

warden                 introduce itself and list the commands
warden --version       print the version

warden serve           run the registry
warden tui             open the dashboard

warden register        claim a port and print it
warden get             print the address of one service
warden ls              list every registered service
warden release         give a port back
warden heartbeat       push a lease out before it runs out
warden pool            show how much of the pool is in use

warden ports           show what is listening on this machine
warden kill            stop whatever is holding a port

warden nodes           list the wardens this one knows about
warden update          say whether a newer warden exists, and fetch it

Every command that talks to a warden takes --url / -u and --token, both of which also read WARDEN_URL and WARDEN_TOKEN. Every command that prints a table also takes --json.

Two flags run through the fleet, and they mean different things:

Flag	On	Means
--all	ls, pool, ports, tui	Ask every warden, not just this one
--node NAME	register, release, heartbeat	Do it on that one warden, through this one

warden kill reads the local machine and ignores --url entirely. warden ports does too, unless --all is given, which needs a hub to ask.

---

warden serve

Run the registry.

Flag	Meaning
--host	Interface to listen on
--port	Port to listen on
--pool 8000-8999	Range of ports to hand out
--reserved 8080,9000-9010	Ports never handed out
--database	Path to the registry database
--no-probe	Do not test ports for existing listeners

Fleet settings have no flags; they are environment only. See Configuration.

warden register

Claim a port. Prints the port and nothing else, so it drops into a script.

Flag	Meaning
--kind, -k	Required. What the service is
--project	Group services of one codebase
--host	Interface the service will bind to, default 127.0.0.1
--preferred-port	Wish for this port, take another if it is not free
--require-port	Insist on this port, fail if it is not free
--ttl	Release the port again after this many seconds
--pid	Process id of the service
--node	Register on that warden in the fleet, through this one

--preferred-port and --require-port cannot both be given.

$ warden register shop-api --kind backend --project shop
8000

warden get

Print one service's address.

$ warden get shop-api
127.0.0.1:8000

Given as node/service, it asks that node through the hub:

$ warden get build-01/build-runner --url http://hub:7010
127.0.0.1:9000

Exits 1 with no service registered as 'x' when it is not there.

warden ls

List registered services.

Flag	Meaning
--project	Only this project
--kind	Only this kind
--all	Ask every warden in the fleet, not just this one

$ warden ls --project shop
SERVICE   KIND      PROJECT  ADDRESS         PID
shop-api  backend   shop     127.0.0.1:8000  -
shop-web  frontend  shop     127.0.0.1:8001  -

--all asks every warden in the fleet and adds a NODE column. Nodes that did not answer are named on standard error, so a pipe still gets a clean table. See Cluster.

warden release

Give a port back to the pool.

$ warden release shop-web
released shop-web

--node build-01 releases it on that warden instead, through the one you asked.

warden heartbeat

Push a lease out before it runs out, for a service registered with a --ttl.

$ warden heartbeat ci-runner --ttl 600
127.0.0.1:9000

Flag	Meaning
--ttl	Seconds from now; without it, the lease it registered with
--pid	Update the recorded process id at the same time
--node	Do it on that warden in the fleet

warden pool

$ warden pool
8000-8999  2 allocated  997 free  1 reserved

Counts only ports inside the pool. A service on a --require-port outside the range is registered but not counted here.

--all reports every node and the fleet totals, with FREE coloured by how little is left — the point of the view being to spot the machine about to run out:

$ warden pool --all --url http://hub:7010
NODE      POOL       HELD  FREE  RESERVED
build-01  9000-9099  4     96    1
hub       8000-8999  2     997   1
web-02    9000-9099  98    2     1

The totals are a sum of what is left, never one pool the fleet shares: two nodes may hand out the same numbers on different machines.

warden ports

What is listening on this machine. Needs no server.

Flag	Meaning
--port	Only this port
--udp / --no-udp	Include UDP sockets, on by default
--all	Ask every warden in the fleet, and add a NODE column

The WARDEN column names the service when the port came from the registry, which needs a warden to be reachable. Without one the column is simply blank; the rest still works.

See Ports and processes.

warden kill

Stop whatever is holding a port. Needs no server.

Argument	Meaning
target	A port, or a process id with --pid

Flag	Meaning
--pid	Read the number as a process id
--force	Kill it outright if it will not stop politely
--yes, -y	Do not ask first

warden nodes

List the wardens this one knows about.

Flag	Meaning
--forget NAME	Remove a node that is not coming back

$ warden nodes --url http://hub:7010
NODE      URL                   POOL       VERSION  STATUS  LAST SEEN
build-01  http://build-01:7010  9000-9099  0.1.0    online  4s ago

warden tui

The dashboard. --interval sets the refresh in seconds, default 2. --all shows the whole fleet instead of one warden.

Key	Action
↑ ↓ j k	Move
tab	Switch between services and ports
n	Step through one node at a time, with --all
r	Reload now
d	Release the service, or stop the process
q	Quit

The ports view works with no warden running at all: it falls back to reading the machine directly, says so in the subtitle, and d stops a process the same way warden kill does. The services view still needs a registry.

Exit codes

0 on success, 1 on any refusal, with the reason on standard error. The message is the same one the API would return, so a script can act on it:

if ! PORT=$(warden register shop-api --kind backend 2>/dev/null); then
    echo "no port available" >&2
    exit 1
fi