CLI Reference
Every servonaut subcommand, flag, and exit code in one place —
written for cron jobs, CI pipelines, and shell scripts.
This is the scripting and automation reference. If you are managing servers
interactively, the Servonaut app is the right tool — just run servonaut.
Most of these commands are also available in the app, and the docs pages show where. For AI agents,
see the MCP Server docs instead.
Per-feature CLI sections (memory build, hetzner, secrets, …) are documented on their
respective feature pages; this page is the
flat, complete reference you can grep.
Global flags
These flags are accepted by servonaut itself before any subcommand.
They affect the current invocation only — none mutate ~/.servonaut/config.json.
| Flag | Description |
|---|---|
--debug |
Enable verbose debug logging to stderr and ~/.servonaut/logs/servonaut.log. |
--demo |
Replace all IPs, account IDs, hostnames, paths, and secrets on every screen with deterministic fakes. A [DEMO] badge confirms it is active. Safe for screen recording and screenshots. |
--update |
Check for a new release on PyPI and apply it in-place (equivalent to pipx upgrade servonaut). |
--install-desktop |
Add an app-menu shortcut that opens Servonaut in a terminal (Linux / macOS). |
--setup-ovh |
Run the guided OVH Cloud credential setup wizard without opening the TUI. |
--mcp |
Start the built-in MCP server over stdio transport (fully headless — never loads the TUI). Requires the mcp extra (pipx install 'servonaut[mcp]', or pipx inject servonaut mcp on an existing install). See the MCP Server docs. |
--mcp-install <agent> |
Auto-register the MCP server into the named coding agent. Accepted values: claude, opencode, cursor, windsurf, vscode, all. |
--ai-provider <name> |
Override the active AI provider for this invocation only. Accepted values: servonaut, openai, anthropic, gemini, ollama. Does not write to config. Also honoured as the SERVONAUT_AI_PROVIDER environment variable. |
--no-tools |
Disable AI tool execution for this invocation — sets allow_tools: false in the outgoing request. Useful for read-only scripted chat. |
--version |
Print the installed version and exit. |
Cancelling any running command with Ctrl+C always exits with code 130 (the SIGINT shell
convention) and prints a one-line Cancelled. message — never a traceback. Two exceptions:
interrupting the post-top-up balance wait skips only the courtesy refresh (the purchase is unaffected,
exit 0), and interrupting servonaut login prints Sign-in aborted.
(exit 130).
Commands
Authentication
servonaut login
Sign in to your Servonaut account via OAuth2 device flow — fully headless, no TUI needed.
| Flag | Description |
|---|---|
--no-browser | Never attempt to open a local browser window — just print the verification URL and code. |
--force | Re-authenticate even when a valid session already exists. |
The command prints a verification URL and a short code. Open the URL in any browser on any device, enter the code,
and the CLI completes sign-in automatically. The session is stored at ~/.servonaut/auth.json (mode
0600) and shared by every CLI subcommand, the MCP server, and the TUI. After sign-in, entitlements
are fetched and cached.
servonaut logout
Revoke the session at servonaut.dev (best-effort — local sign-out proceeds even if the server is unreachable)
and delete ~/.servonaut/auth.json. Takes no flags.
Relay listener — servonaut connect
Manage the relay listener that lets your hosted AI agents and web actions dispatch tool calls to your machine. Team-mates' tool calls run on their own machines, never on yours. The TUI starts this listener automatically after you sign in; use these flags on headless boxes.
| Flag | Description |
|---|---|
| (no flag) | Run the relay in the foreground; Ctrl+C to stop. |
--bg | Detach and run in the background; writes a PID file at ~/.servonaut/relay.pid. |
--status | Show local and backend connection state, including a divergence warning when they disagree. |
--stop | Send SIGTERM to the background listener. |
--reconnect | Stop and immediately restart the listener — heals a stale SSE socket. |
--force-bg | Take over from the TUI's in-process listener. |
The listener uses your stored servonaut login session (with automatic token refresh).
Setting both SERVONAUT_RELAY_TOKEN and SERVONAUT_USER_ID in the environment
overrides the session (legacy/CI mode).
When running with a logged-in session, the listener also executes tool calls dispatched by AI chats.
Approval is policy-driven (no human present to confirm): relay.ai_tool_auto_approve in
~/.servonaut/config.json caps auto-approval at "readonly", "standard"
(default), or "dangerous". Tools above the tier are denied. Every execution is appended to
~/.servonaut/mcp_audit.jsonl with source="ai_chat".
AI — servonaut ai
Headless access to the Servonaut AI gateway. All subcommands require a valid login session.
See Exit codes for the shared ai error code table.
Requires an active Solo & Teams subscription.
servonaut ai chat <prompt>
| Flag / argument | Default | Description |
|---|---|---|
<prompt> (required) | — | The user message. Wrap in quotes for multi-word prompts. |
--stream | off | Print the answer to stdout as it is written. Without this flag the command waits for the full response (buffered mode). |
--tools | off | Enable tool execution in buffered mode. Buffered mode defaults tools off; streaming mode enables them. |
--no-tools | off | Explicitly disable tool execution. Overrides --tools if both are given. |
--ai-provider <name> | from config | Override the provider for this invocation only. |
servonaut ai quota
Show your AI balance: what's left of this month's allowance, any top-up balance, and when the
allowance renews. Exits 2 when you are not signed in and 3 when your plan
has no hosted AI.
| Flag | Description |
|---|---|
--json | Output the balance as JSON, for scripts. |
servonaut ai conversations
Subcommands for managing conversation history:
| Subcommand | Flags / arguments | Description |
|---|---|---|
list |
--limit <n> (default 25, max 100), --before <iso> (pagination cursor), --status active|archived|deleted, --json |
List conversations, most-recent first. |
show <uuid> |
--json |
Print a full conversation thread (all messages) to stdout. |
export <uuid> <path> |
--format md|json (default md), --force (overwrite) |
Export a conversation to a local file. <path> must resolve within the current working directory or ~/Downloads/; path traversal is rejected. |
archive <uuid> |
— | Move a conversation out of the active list without deleting it. |
delete <uuid> |
— | Soft-delete a conversation. Still listable with --status deleted. |
servonaut ai topup [<pack>]
Open a Stripe Checkout page to add to your AI balance. <pack> is
one of
small (£5, adds £5.00) or large (£20, adds £20.00);
if omitted, the command lists the packs. It opens the checkout URL in your default browser via
$BROWSER. After purchase completes, your balance typically refreshes within 60 seconds.
A top-up is used after your monthly allowance and lasts 365 days from purchase.
servonaut ai provider reset
Clear the persistent provider preference and all dismissed-banner flags. The provider-picker decision tree runs again on the next chat start. Takes no additional arguments.
Memory — servonaut memory
Build and manage the per-server fact cache. Full documentation is on the Server Memory page. Solo & Teams
| Subcommand | Key flags | Description |
|---|---|---|
build <instance> | --all | Probe and persist a server's memory modules. --all runs against the whole fleet. |
refresh <instance> | — | Re-probe a previously built instance to update stale modules. |
show <instance> | --json | Print the latest memory snapshot to stdout. |
pin <instance> | — | Pin the current snapshot so drift detection compares against it. |
annotate <instance> | — | Add a text annotation to a server's memory record. |
export <instance> | --format json|md | Export the memory snapshot to a file. |
clear <instance> | --yes | Delete all stored memory for an instance. Irreversible without --yes. |
Hetzner Cloud — servonaut hetzner
Hetzner Cloud lifecycle from scripts. Full documentation is on the Hetzner Cloud page.
| Subcommand | Key flags | Description |
|---|---|---|
list | --json | List all servers in the configured Hetzner project. |
create | — | Create a new Hetzner server (interactive prompts for name, type, location, image, SSH key). |
destroy <id> | --yes | Delete a server by ID. --yes skips the confirmation prompt for unattended use. |
Secrets — servonaut secrets
Inspect and configure the secrets backend integration. Full documentation is on the Secrets & Integrations page. Solo & Teams
| Subcommand | Description |
|---|---|
status | Show the current secrets backend configuration and connection state. |
setup | Run the guided wizard to connect a secrets backend (e.g. Bitwarden vault). |
JSON output
The following commands accept a --json flag and emit structured output to stdout
suitable for piping into jq or parsing in CI scripts. Non-zero exit codes are
signalled by the process exit status, not via a JSON error field.
| Command | Output shape (key fields) |
|---|---|
servonaut ai quota --json |
Your AI balance and the date the monthly allowance renews |
servonaut ai conversations list --json |
JSON array; each item has id, updated_at, status, title |
servonaut ai conversations show <uuid> --json |
Object with id, messages array (role, content) |
servonaut ai conversations export <uuid> <path> --format json |
Writes JSON to disk; stdout is a one-line confirmation. |
servonaut memory show <instance> --json |
Full memory snapshot object with module sub-objects. |
servonaut hetzner list --json |
JSON array of server objects (id, name, status, datacenter, ipv4). |
servonaut connect --status |
Human-readable only — no --json flag. In scripts, prefer the account API's CLI status endpoint or check the exit code. |
Exit codes
General
| Code | Meaning |
|---|---|
0 | Success. |
1 | Generic error (see stderr for details). |
130 | Interrupted — Ctrl+C / SIGINT. Always clean; never a traceback. |
AI subcommands (servonaut ai *)
All servonaut ai commands share these additional exit codes:
| Code | Meaning | Recovery |
|---|---|---|
0 | Success. | — |
1 | Error — including an empty AI balance; stderr names the reason (for example Error [quota_exhausted]). | Check stderr. For an empty balance, run servonaut ai topup or wait for your monthly allowance to renew. |
2 | Unauthenticated — no valid session. | Run servonaut login. |
3 | Insufficient entitlement — Solo or Teams plan required. | Upgrade at servonaut.dev/pricing. |
4 | Invalid arguments (for example an unknown top-up pack). | Check the command's usage. |
130 | Ctrl+C. | — |
Check exit codes explicitly in scripts rather than relying on stderr text. Example:
Headless authentication
The device flow works fully headless — no browser on the machine running the CLI is required. The flow for a CI box or a server with no desktop:
Tokens are stored at ~/.servonaut/auth.json (mode 0600). They are shared by every
CLI subcommand, the MCP server, and the TUI — sign in once per machine. servonaut logout revokes
the session server-side and deletes the local token file.
For CI environments where the device flow is impractical, you can set
SERVONAUT_RELAY_TOKEN and SERVONAUT_USER_ID in the environment to
provide credentials directly to servonaut connect. The stored session is used
when these variables are unset.
Scripting examples
Nightly memory build (cron)
Keep server memory fresh on a schedule so AI context is always current. Run as the user
whose ~/.servonaut/auth.json holds a valid session.
CI health check with --json and jq
Confirm the API is reachable, the session is valid and the plan includes hosted AI as a pre-flight step in a pipeline.
Background relay via a systemd user unit
Keep the relay listener running across reboots so AI agents can reach your machine at any time.