serverctl

The CLI for app-lb's admin API. By default it talks to http://127.0.0.1:9090; reach a remote server over an SSH tunnel (ssh -L 9090:127.0.0.1:9090 host) and save it as a context with serverctl login.

Contexts & identity

serverctl login                  # verify credentials, save as a context
serverctl whoami                 # which server, as whom, allowed to do what
serverctl config get-contexts    # manage saved contexts
serverctl logout

Credentials are the Basic pair or an app-token (--token, or APP_LB_TOKEN). Machine output is everywhere: -o json, -o yaml, -o name.

Reading the fleet

serverctl get deployments        # also: vms, certs, secrets, jobs, workflows
serverctl describe web           # spec, pool, backends, traffic
serverctl status                 # whole-LB overview
serverctl top                    # CPU/memory for deployments, VMs or the host
serverctl feed                   # namespaces with events — see below

Deployments

serverctl apply -f web.json      # create or replace from a spec (JSON or YAML)
serverctl create deployment …    # the flag-driven alternative
serverctl edit web               # fetch spec → $EDITOR → put back
serverctl scale web --min 1 --max 4
serverctl restart web            # recycle VMs one eviction at a time
serverctl rollout status web     # watch the pool converge
serverctl delete web

Changing one thing

serverctl set image web web-rootfs-v2     # rebuilds the pool
serverctl set env web RUST_LOG=debug      # KEY=VALUE, or KEY- to remove
serverctl set upstreams legacy 10.0.0.5:3000
serverctl set route web --host web.example.com
serverctl set build web --repo https://github.com/example/web

Images

serverctl build web              # run the spec's build block, roll the pool
serverctl pull web               # pull the spec's artifact instead
serverctl artifact login …       # talk to an artifact store directly
serverctl update legacy          # static deployment: run its update commands

Inside a VM

serverctl exec web -- uname -a   # one command; guest exit code becomes serverctl's
serverctl shell web              # interactive PTY (alias: ssh)

Both go through app-lb, so they work wherever the admin API does — and they wake a scale-to-zero deployment that has no VM running.

Tokens

serverctl token mint NAME [--admin none|view|admin]
                     [-d ID]... [--all-deployments]
                     [--namespace NS] [--expires-in HOURS] [-q]
serverctl token list
serverctl token describe ID
serverctl token set ID [--name…] [--admin…] [-d…] [--never-expires]
serverctl token revoke ID

The secret prints once, on stdout, with commentary on stderr — so TOKEN=$(serverctl token mint agent -d web -q) captures exactly the credential. The listing's scope column shows a namespace wall as team-a:* or team-a:web. See Namespaces for what --namespace means.

Feeds

serverctl feed                   # which namespaces have events
serverctl feed team-a            # events, newest first (-n limits)
serverctl feed team-a --xml      # the RSS document, verbatim

$ serverctl feed team-a
WHEN         KIND      DEPLOYMENT  WHAT
2m ago       issue     web         web: cold start timed out — a request waited 120s… (×3)
1h ago       deployed  web         web deployed — serving at https://web.example.com

See The event feed for how events get there in the first place.

Libraries

The same API surface ships as libraries, wire-pinned against app-lb's golden fixtures so a field can't silently go missing:

Rust — the serverctl crate: an async Client, a blocking wrapper, and client.raw() for verbatim JSON.
TypeScript — sdk/typescript: new Serverctl({ server, token }) with typed deployments(), exec(), mintToken(), feeds(), feedEvents()…

serverctl completion bash        # also zsh, fish, elvish, powershell