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 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

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.

warden ports and warden kill are the exceptions: they read the local machine and ignore --url entirely.

---

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

--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

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

$ 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  -

warden release

Give a port back to the pool.

$ warden release shop-web
released shop-web

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.

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

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.

Key	Action
↑ ↓ j k	Move
tab	Switch between services and ports
r	Reload now
d	Release the service, or stop the process
q	Quit

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