Skip to main content

​
Overview

GroupCommands
Authenticationlogin, logout, auth status
Agents (top-level)install --from, list, status, stop, resume, kill, delete, logs, events, steer
Credentialscredential add, credential show, credential list, credential delete
Workspacesworkspace add, workspace list, workspace use, workspace show, workspace credentials, workspace delete
External agentsagent add, agent list, agent delete
Integration grantsgrant list, grant delete
Billingbilling show
Diagnosticsdoctor
Every command accepts the global flags. Every command that returns structured data supports --json for machine-readable output.

​
Authentication

​
zombiectl login

Authenticate via a Clerk-backed browser device flow with terminal-side verification. Opens your default browser to the approval page; on Approve, the page displays a 6-digit verification code which you type back into the CLI to complete login. The verification code binds the browser approver to the terminal user — phishing the URL alone is not enough to mint a credential. 
zombiectl login

# Label this device for visibility in `auth status` and on the approval page
zombiectl login --token-name "kishore-macbook"

# Non-interactive (CI, scripts): supply a token instead of the browser flow
ZOMBIE_TOKEN="$MY_TOKEN" zombiectl login
# …or pipe it so it never lands in shell history
printf '%s' "$MY_TOKEN" | zombiectl login
After the token persists, login also fetches GET /v1/tenants/me/workspaces and writes the first workspace into local state as current_workspace_id. Signup auto-provisions a default workspace, so a fresh npm i -g @usezombie/zombiectl && zombiectl login is enough to reach zombiectl doctor green — workspace add is only needed if you want a second or custom-named workspace, or if the workspace fetch failed (login still exits 0 in that case). Flags:
  • --token <token> — authenticate non-interactively with a token directly, skipping the browser entirely; the token is validated against the server and persisted. Prefer the ZOMBIE_TOKEN env var or piping the token on stdin to keep it out of your shell history. --token-name is ignored for any non-browser token source — --token, the ZOMBIE_TOKEN env var, or piped stdin — since there’s no browser session to label.
  • --token-name <label> — human-readable device label persisted alongside the token. Defaults to your platform family (macos-cli, linux-cli, windows-cli). Shows up on the dashboard approval page (so you know which terminal you’re approving for) and in zombiectl auth status.
  • --no-open — print the auth URL instead of opening a browser automatically.
  • --force — skip the “you’re already logged in as <name>, replace?” prompt.
  • --no-input — fail fast instead of prompting for the verification code. Supply a token non-interactively via --token, the ZOMBIE_TOKEN env var, or piped stdin.
zombiectl login resolves a token in priority order — the --token flag, then the ZOMBIE_TOKEN environment variable, then a token piped on stdin — and falls back to the browser device flow only on an interactive terminal with none of those set. A non-interactive shell (--no-input, or no terminal) with no token exits immediately with an error instructing you to supply one via --token, ZOMBIE_TOKEN, or piped stdin — the verification code can’t be entered without a terminal. The login session lives 5 minutes; an unfinished approval expires automatically. The verification code’s 6-digit shape is checked locally before it’s sent, so a typo just re-prompts. Wrong (but well-formed) code attempts cap at 5 per session — a sixth wrong code aborts the session and you re-run zombiectl login.

​
zombiectl logout

Removes local credentials (~/.config/zombiectl/credentials.json) and aborts any in-flight zombiectl login flows you have pending. 
zombiectl logout
Does NOT revoke your active session token — JWTs are short-lived (~15 min) and expire on their own. Does NOT touch the ZOMBIE_TOKEN environment variable — if it’s set, subsequent commands continue to use that token until you unset it.

​
zombiectl auth status

Inspect the stored credential without re-authenticating. Resolves the token source (file vs ZOMBIE_TOKEN env vs none), decodes the JWT claims (iss, aud, sub, metadata.tenant_id, metadata.role, exp), surfaces the token_name label persisted at login, and probes GET /v1/tenants/me/billing to check the token is still accepted by the server. 
zombiectl auth status
zombiectl auth status --json
Exit codes:
  • 0 — token valid, or server unreachable (transient API issues don’t poison local state).
  • 1 — no credentials configured, or the server rejected the token (UZ-AUTH-001 / UZ-AUTH-002 / TOKEN_EXPIRED). Re-run zombiectl login.
The probe result is one of valid (200 from the billing endpoint), unauthorized (server rejected), or unreachable (network / 5xx). unreachable is informational — the local token is unchanged.

​
Agents

​
zombiectl install --from <path>

Reads SKILL.md and TRIGGER.md from <path>, validates them, and uploads to the active workspace. The two markdown files are the configuration; the usezombie-install-platform-ops host-agent skill is what generates them under .usezombie/<zombie>/ in your repo. The --from flag is required — there are no bare-name template aliases. 
zombiectl install --from ~/.config/usezombie/samples/platform-ops
The samples/ directory ships with zombiectl and contains the flagship platform-ops sample. The host-agent install skill (/usezombie-install-platform-ops) drives this command under the hood. See Quickstart and Templates.

​
zombiectl list

List agents in the active workspace. Keyset-paginated over (created_at, id) — the dashboard /zombies page uses the same contract. 
zombiectl list --limit 20
FlagDefaultPurpose
--workspace-id <id>(active)Override the active workspace for this call.
--limit <n>20Page size. Clamped to 100.
--cursor <cursor>(none)Cursor from a previous response’s cursor field.
--jsonoffEmit the raw {items, total, cursor} envelope for scripting.
Human-readable output prints a table and, when more pages remain, a “Next” hint with the exact cursor to pass back.

​
zombiectl status

List every agent in the current workspace with state, events processed, and budget consumed. 
zombiectl status

​
Agent lifecycle: stop / resume / kill / delete

Four verbs control an agent’s lifecycle, in increasing order of irreversibility:
VerbWhat it doesReversible?
stop <zombie_id>Halt the running session. New events stop dispatching; in-flight run finishes cleanly.Yes — zombiectl resume.
resume <zombie_id>Resume from stopped or auto-paused state.—
kill <zombie_id>Mark terminal. The agent won’t process events again, but its row, history, and webhook URL persist.No, but the agent can be deleted after.
delete <zombie_id>Hard-delete. Removes the agent row and its webhook URL. Must kill first.No.
zombiectl stop   zmb_2041   # pause; resumable
zombiectl resume zmb_2041   # back to active
zombiectl kill   zmb_2041   # terminal; webhook still 200s but routes nowhere new
zombiectl delete zmb_2041   # hard-delete; webhook URL starts returning UZ-WH-001
State is checkpointed at every transition — nothing on the activity stream is lost until the final delete.

​
zombiectl logs <zombie_id>

Print the agent’s recent activity stream — newest-first, paginated. 
zombiectl logs zmb_2041
zombiectl logs zmb_2041 --limit 50 --cursor <next_cursor>
zombiectl logs zmb_2041 --json
FlagDefaultPurpose
--limit <n>20Page size.
--cursor <cursor>(none)Pagination cursor returned as next_cursor in a previous response.
--jsonoffEmit the raw { items, next_cursor } envelope.
The agent ID may also be passed via --zombie <id> for scripting symmetry with events.

​
zombiectl events <zombie_id> — filtered history

Richer filter surface than logs. Use this when you need to slice by actor or time window — for example, when troubleshooting a specific webhook source. 
zombiectl events zmb_2041 --actor 'webhook:*' --since 2h
zombiectl events zmb_2041 --actor 'steer:*' --since 7d --limit 100
zombiectl events zmb_2041 --json | jq 'select(.error)'
FlagDefaultPurpose
--actor <glob>(none)Filter by actor — webhook:*, cron:*, steer:*, continuation:*.
--since <duration>24hTime window — Go-style duration (2h, 7d) or RFC 3339 timestamp.
--cursor <cursor>(none)Pagination cursor from a previous response.
--limit <n>50Max events per page.
--jsonoffEmit raw JSON for scripting.
There is no --follow/streaming-tail flag today. To watch live, poll events --since 30s from a script.

​
zombiectl steer <zombie_id> [message]

Post a steer message — a manual trigger that uses the same reasoning loop as a webhook event. Useful for ad-hoc investigation or before a webhook is wired up. 
zombiectl steer zmb_2041
zombiectl steer zmb_2041 "morning health check — anything red?"
echo "check the latest deploy event" | zombiectl steer zmb_2041
printf "check the latest deploy event\ncheck memory usage\n" | zombiectl steer zmb_2041 --tty
FlagDefaultPurpose
--tty(auto on TTY)Force the interactive REPL even when stdin is piped — each line is a separate turn; exits at end-of-file.
--jsonoffEmit the steer result as JSON.
When you invoke zombiectl steer <zombie_id> from a terminal (TTY) and omit the message, zombiectl opens a read-eval-print loop (REPL). Each submitted line posts one steer message, streams the reply, then returns to the prompt. Press Ctrl-D to exit cleanly, or Ctrl-C to cancel the active stream and exit. Explicit messages stay single-shot, even from a terminal. Piped input also stays single-shot by default so automation and agents can continue invoking the command once per turn. Add --tty to force the REPL over piped input; zombiectl exits when the pipe reaches end-of-file. The reply streams back live; the result also persists to the activity stream for replay.

​
Credentials

​
zombiectl credential add <name> --data=@-

Store a JSON-shaped secret in the current workspace vault. The agent references it by name from TRIGGER.md. Always pipe JSON on stdin via --data=@-. Never pass it inline as --data='{...}' — that puts the secret in shell history and process argv: 
zombiectl credential add github --data=@- <<'JSON'
{ "api_token": "ghp_...", "webhook_secret": "<32-byte hex>" }
JSON
Default behaviour is skip-if-exists. Use --force to overwrite for rotation. See Workspace credentials for the full vault model.

​
zombiectl credential show <name>

Print metadata (created, last-rotated). Values are never returned.

​
zombiectl credential delete <name>

Remove a credential from the workspace vault. Any agent still referencing it will fail with UZ-ZMB-003 (credential missing) on the next event until you re-add it (or update TRIGGER.md). See Error codes.

​
zombiectl credential list

List credential names and creation timestamps in the current workspace. Values are never returned. 
zombiectl credential list

​
Workspaces

​
zombiectl workspace add [name]

Create a new workspace under the current tenant and set it as active. The optional positional name is a human label; if omitted, the server picks a default. There is no repo URL — workspaces are not bound to a specific GitHub repo at creation time. 
zombiectl workspace add                       # server-assigned name
zombiectl workspace add my-platform-ops       # named workspace
Returns the new workspace_id and persists it as current_workspace_id in ~/.config/zombiectl/workspaces.json. Subsequent commands use it by default.

​
zombiectl workspace list

List all configured workspaces with an active marker. 
zombiectl workspace list

​
zombiectl workspace use <id>

Set the active workspace persistently. Writes current_workspace_id to ~/.config/zombiectl/workspaces.json; every subsequent command that accepts --workspace-id defaults to this value when the flag is omitted. 
zombiectl workspace use ws_abc123
Errors out if the id isn’t in the local list (run zombiectl workspace list first). The dashboard’s own active_workspace_id cookie and the CLI config are independent — switching one does not affect the other. See Workspaces overview.

​
zombiectl workspace show

Show the active workspace (or a specific one via --workspace-id) — mirrors the dashboard Settings page. 
zombiectl workspace show
Prints the workspace’s workspace_id, name, created_at, and active marker. Use --json for scripting.

​
zombiectl workspace delete <id>

Delete a workspace and everything in it. Stops accepting new events immediately, lets in-flight runs finish, retains run history for 30 days. Cannot be undone — recreating a workspace produces a fresh workspace_id and fresh zombie_ids, so any upstream webhooks pointing at the old workspace’s agents need to be re-wired. 
zombiectl workspace delete ws_abc123

​
External agents

External agents are API-key–authenticated callers (LangGraph, CrewAI, Composio, your own code) that drive a specific agent programmatically.

​
zombiectl agent add

Mint an API key bound to one agent. 
zombiectl agent add --workspace ws_abc --zombie zm_xyz --name my-agent
The raw key (zmb_…) is returned once; store it in your secret manager.

​
zombiectl agent list

List every external agent key in a workspace. 
zombiectl agent list --workspace ws_abc

​
zombiectl agent delete <agent-id>

Revoke an external agent key. 
zombiectl agent delete --workspace ws_abc ag_01JABC...

​
Integration grants

Integration grants are per-agent permissions to reach a third-party service (Slack workspace, GitHub repo) that the agent requested interactively.

​
zombiectl grant list --zombie <id>

List pending and approved grants for an agent. 
zombiectl grant list --zombie zm_01JABC...

​
zombiectl grant delete --zombie <id> <grant-id>

Revoke a granted integration. Further attempts by the agent to reach that integration fail with UZ-GRANT-003. 
zombiectl grant delete --zombie zm_01JABC... gr_01JXYZ...

​
Billing

​
zombiectl billing show

Show the tenant’s wallet balance and recent charges. Tenant-scoped (the wallet is tenant-level), not per-workspace. 
zombiectl billing show
zombiectl billing show --limit 50
zombiectl billing show --cursor <next_cursor>
zombiectl billing show --json
FlagDefaultPurpose
--limit <n>(server)Page size for the charges list.
--cursor <cursor>(none)Pagination cursor from a previous response.
--jsonoffEmit raw JSON for scripting.
For per-agent spend breakdowns, use zombiectl logs <zombie_id> --json and aggregate the tokens / wall_ms fields client-side. Top-ups and payment-method updates happen at app.usezombie.com/billing.

​
Tenant provider

By default your tenant runs on platform-managed inference — usezombie holds a Fireworks key for Kimi K2.6 and bills you for the tokens at retail rate, bundled into the run charge. You can flip the tenant to self-managed at any time: store your own provider credential (Anthropic, OpenAI, Fireworks, Together, Groq, Moonshot, OpenRouter) in the vault under a name you choose, then point the tenant at it. On self-managed runs the per-second run fee still applies, but there is no added per-token cost from usezombie — you pay your provider directly. See pricing for current rates.

​
zombiectl tenant provider show

Print the active posture, model, context-cap, and (for self-managed) the credential name. --json for the structured shape. 
zombiectl tenant provider show
zombiectl tenant provider show --json

​
zombiectl tenant provider set

Activate a self-managed credential for the tenant. The credential must already exist in the workspace vault (zombiectl credential add <name>). The command validates the credential structure, resolves the model’s context cap from the cap.json endpoint, and pins both into the tenant’s provider row. 
# 1. Store the provider credential
zombiectl credential add account-fireworks --data='{"provider":"fireworks","api_key":"fw_…","model":"accounts/fireworks/models/kimi-k2.6"}'

# 2. Activate it for the tenant
zombiectl tenant provider set --credential account-fireworks
In-flight events finish under the snapshot they were claimed under; the next event’s debits use the new posture.

​
zombiectl tenant provider reset

Drop the explicit tenant_providers row and fall back to the platform-managed synth-default. 
zombiectl tenant provider reset
For the install-time vs trigger-time resolution flow, the frontmatter overlay sentinels, and the provider routing details, see docs/architecture/user_flow.md §8.7 and docs/architecture/billing_and_provider_keys.md. The architecture is the canonical reference; this page is the command surface.

​
Diagnostics

​
zombiectl doctor

Verify API connectivity, authentication, and local configuration. Does not require authentication. 
zombiectl doctor
See docs/architecture/ for the full technical reference.