The servers binary is a flat Commander.js CLI. Run servers --help for the command list and servers <command> --help for the help generated by the installed version.
Usage: servers [options] [command]
Options:
--db <path> Path to SQLite database
--format <format> Output format (table, json) (default: table)
-V, --version Output the version number
-h, --help Display help
--format json applies globally. Commands that expose --json accept it as a local equivalent. JSON is recursively redacted for keys that look like secrets, tokens, passwords, credentials, authorization values, cookies, sessions, or private keys.
With no command, servers prints a dashboard summary of server status, active agents, recent operations, and recent traces. With --format json, it prints the same categories as a JSON object.
The package also registers event commands from @hasna/events under the servers CLI, including its webhook command namespace as event-webhooks. Those commands follow the installed @hasna/events version; use servers --help for that externally supplied surface. The commands below are the 50 commands defined by this repository.
Human-readable list commands default to 20 rows and accept --limit <n> and --cursor <n>. Their footer reports the total and next cursor. --verbose adds columns while the corresponding *:get command prints a complete record.
Unbounded entity lists preserve their historical complete JSON output when neither --limit nor --cursor is supplied. operations --json, traces --json, and webhooks:logs --json retain legacy default limits of 50, 100, and 50 respectively. Supplying pagination options always bounds the JSON result.
IDs may be full UUIDs or unambiguous UUID prefixes where the argument says partial IDs are accepted. Server selectors also accept slugs and, in resolution paths, exact names.
| Command | Options | Behavior |
|---|---|---|
servers (alias server) |
--project <id>, --limit <n>, --cursor <n>, --verbose, --json |
List registered servers, optionally filtered by project. |
servers:add (alias server:add) |
Required: --name <name>; optional --slug, --hostname, --path, --description, --status, --project, --metadata <json>, --tailscale-hostname, --tailscale-port |
Register a server. Status defaults to unknown; metadata must be a JSON object. |
servers:update <id-or-slug> (alias server:update) |
--name, --slug, --hostname, --path, --description, --status, --project, --metadata <json>, --tailscale-hostname, --tailscale-port |
Update supplied fields. Metadata and Tailscale options are merged into the existing metadata object. |
servers:get <id-or-slug> (alias server:get) |
--json |
Show a server and its computed Tailscale URL. |
servers:delete <id-or-slug> (alias server:delete) |
None | Delete an unlocked server. |
servers:lock <id-or-slug> (alias server:lock) |
Required: --agent <id> |
Lock a server against modification. |
servers:unlock <id-or-slug> (alias server:unlock) |
Required: --agent <id> |
Unlock a server held by the agent. |
servers:heartbeat <id-or-slug> (alias server:heartbeat) |
None | Update the server heartbeat timestamp. |
Valid server statuses are online, offline, starting, stopping, restarting, deploying, maintenance, and unknown.
| Command | Options | Behavior |
|---|---|---|
servers:init (alias server:init) |
--name, --path, --project-name, --description, --command, --port, --health-url, --readiness-url, repeatable --env KEY=VALUE, --log-file, --force, --json |
Detect or explicitly configure an app, create its project when needed, and register it offline. --force updates an existing matching slug. |
servers:start <id-or-slug> (alias server:start) |
--agent, --session, --reason, --command, --cwd, --port, --health-url, --readiness-url, repeatable --env, --log-file, --timeout, --lock-timeout, --wait-lock, --no-wait, --force, --json |
Start a detached local process and wait for readiness unless --no-wait is set. |
servers:restart <id-or-slug> (alias server:restart) |
Start options plus --stop-timeout; also --force |
Stop the discovered process tree, start a replacement, and wait for readiness. --force permits SIGKILL escalation when the old process does not stop gracefully. |
servers:stop <id-or-slug> (alias server:stop) |
--agent, --session, --reason, --timeout, --stop-timeout, --lock-timeout, --wait-lock, --no-wait, --force, --json |
Stop the managed process tree. Normal verified stop escalates through SIGKILL when needed; --no-wait only sends SIGTERM and records stopping. |
servers:status <id-or-slug> (alias server:status) |
--refresh, --timeout, --json |
Probe process/readiness state. --refresh persists status and heartbeat. |
servers:wait <id-or-slug> (alias server:wait) |
--state online|offline (default online), --timeout (default 30000), --json |
Poll every 250 ms until ready or stopped; exits nonzero on timeout. |
servers:logs <id-or-slug> (alias server:logs) |
--lines <n> (default 80) |
Print the tail of the configured managed log file. |
servers:debug <id-or-slug> (alias server:debug) |
--json |
Show the server, runtime snapshot, lifecycle lock, and ten recent operations and traces. |
See Local runtime for detection and safety semantics. Lifecycle commands reject production-cloud records.
| Command | Options | Behavior |
|---|---|---|
agents |
--status active|archived, --limit, --cursor, --verbose, --json |
List agents. |
agent:get <id-or-name> (alias agent:show) |
--json |
Show an agent by ID, UUID prefix, or exact name. |
agent:register |
Required: --name; optional --description, comma-separated --capabilities, --session, --working-dir |
Register or reclaim an agent according to session/staleness rules. Working directory defaults to cwd. |
agent:update <name> |
--description, comma-separated --capabilities, --session, --working-dir |
Update an agent selected by exact name. |
agent:heartbeat <name> |
None | Heartbeat an agent selected by name or ID. |
agent:archive <name> |
None | Archive an agent and clear its session. |
agent:release <name> |
None | Clear the agent's session and refresh its last-seen timestamp without archiving it. |
| Command | Options | Behavior |
|---|---|---|
operations |
--server, --status, --limit, --cursor, --verbose, --json |
List operations, optionally filtered by server and status. |
operation:add |
Required: --server, --type; optional --agent, --session |
Create a pending operation. |
operation:get <id> (alias operation:show) |
--json |
Show an operation by ID or UUID prefix. |
operation:start <id> |
None | Transition a pending operation to running. |
operation:complete <id> |
None | Transition an operation to completed. |
operation:fail <id> |
--error <message> |
Transition an operation to failed; the default message is Unknown error. |
operation:cancel <id> |
None | Cancel a pending or running operation. |
operation:update <id> |
--status pending|running|completed|failed|cancelled, --error |
Update an operation's status or error. |
operation:delete <id> |
None | Delete an operation. |
Operation types are start, stop, restart, deploy, configure, status_check, and custom.
| Command | Options | Behavior |
|---|---|---|
traces |
--server, --agent, --limit, --cursor, --verbose, --json |
List audit traces by server or agent. |
trace:add |
Required: --server, --event; optional --operation, --agent, --details <json> |
Create a trace; details must be a JSON object. |
trace:get <id> (alias trace:show) |
--json |
Show a trace by ID or UUID prefix. |
traces:delete <id-or-slug> |
None | Delete all traces for a server. |
| Command | Options | Behavior |
|---|---|---|
projects |
--limit, --cursor, --verbose, --json |
List projects. |
project:add |
Required: --name, --path; optional --description |
Register a project. |
project:get <id-or-path> (alias project:show) |
--json |
Show a project by ID, UUID prefix, or exact path. |
Project update and delete operations are available through the SDK and MCP tools, not local CLI commands.
| Command | Options | Behavior |
|---|---|---|
webhooks |
--limit, --cursor, --verbose, --json |
List webhooks. Secrets are redacted in output. |
webhook:add |
Required: --url; optional comma-separated --events, --secret, --server, --project |
Create an active HTTPS webhook, optionally scoped to a server or project. |
webhook:get <id> (alias webhook:show) |
--json |
Show a webhook with its secret redacted. |
webhook:delete <id> |
None | Delete a webhook. |
webhook:toggle <id> |
None | Toggle a webhook between active and inactive. |
webhooks:logs (alias webhook:deliveries) |
--webhook, --limit, --cursor, --verbose, --json |
List delivery attempts, optionally for one webhook. Sensitive payload fields are redacted. |
Webhook creation requires HTTPS and rejects obvious localhost, metadata, and private-range targets. Delivery resolves hostnames again before sending, signs the exact JSON body with X-Webhook-Signature when a secret is set, retries up to three times with exponential backoff, and caps concurrent deliveries at 20.
| Command | Options | Behavior |
|---|---|---|
monitor |
--interval <ms> (default 5000) |
Continuously redraw server status until interrupted. |
export |
--output <path> |
Export servers, agents, operations, traces, projects, and webhooks as JSON to stdout or a file. Delivery logs and resource locks are not included. |
import |
Required: --input <path> |
Import a prior JSON export. |
completion <shell> |
bash, zsh, or fish |
Print a shell completion script. Bash includes command options; zsh and fish expose command-level completion. |
dashboard |
None | Start the interactive Ink dashboard. |