Command-line tool

layerbeat is a single 1.5 MB binary that starts in about 2 ms. lb is a short alias for the same program. It only talks to the public API, so everything here works the same as the reference.

Install and sign inCopy Anchor Link

layerbeat --help                # or: lb --help
layerbeat login                 # paste an API key from the console (Access & keys)
layerbeat whoami

The token comes from LAYERBEAT_API_KEY or layerbeat login, which stores it readable only by you. Tokens are never accepted as command-line arguments and never printed. Point the tool at another server with --api-url or LAYERBEAT_API_URL.

Everyday commandsCopy Anchor Link

layerbeat plans --region sgp
layerbeat quote --region sgp --plan SG-B224-W --image "Ubuntu 24.04"
layerbeat ssh-key add laptop --file ~/.ssh/id_ed25519.pub
layerbeat new agent-01 --region sgp --plan SG-B224-W --image ubuntu-24-04 --ssh-key laptop --max-price 6 --wait
layerbeat ssh agent-01 -- uptime
layerbeat fw add agent-01 --port 443
layerbeat ls -q | xargs -n1 layerbeat stop --wait
layerbeat topup 25
layerbeat rm agent-01 --confirm agent-01

--plan and --image accept IDs or names. An ambiguous name lists the choices instead of guessing.

All commandsCopy Anchor Link

The contract for agentsCopy Anchor Link

• Output is JSON when stdout is not a terminal, or with --json. Shapes are the API's own; errors go to stderr as the API's error envelope and stdout stays empty.
• Exit codes: 0 ok, 2 usage, 3 auth, 4 not found, 5 invalid state, 6 not enough credit or above --max-price, 7 rate limited, 8 wait timeout, 9 unavailable, 10 out of stock or quota.
• Purchases are always quoted first. --max-price refuses anything more expensive, and repeating a command with the same --idempotency-key returns the original result instead of buying twice.
• Deletion needs --confirm with the exact server name. --no-input never prompts.