Commands Reference

CLI Commands

Every ZoarkBot command explained. Run these in your terminal on the machine where ZoarkBot is installed.

Command	What it does	When to use
zoarkbot start	Starts the ZoarkBot gateway process in the background	After installing or after your server reboots
zoarkbot stop	Gracefully stops the gateway process	To shut down ZoarkBot without deleting data
zoarkbot restart	Stops then starts the gateway. Also reloads your config file.	After editing zoarkbot.json, after updates, or when something seems stuck
zoarkbot status	Shows gateway health: running/stopped, channel connections, active sessions, config state	First thing to run when something is wrong
zoarkbot token	Prints your gateway access token. Paste this into Mission Control to connect.	When logging in to mc.zoarkai.org for the first time, or after a token change
zoarkbot logs	Streams live logs from the gateway. Shows agent activity, errors, and events.	Debugging issues, or watching agent activity in real-time
zoarkbot setup	Interactive first-time setup wizard. Creates ~/.zoarkbot/zoarkbot.json with your answers.	Only during initial installation
zoarkbot update	Updates ZoarkBot to the latest version. Pulls new binary/package and restarts.	To get new features and bug fixes. Check mc.zoarkai.org for release notes.

zoarkbot start

Starts the ZoarkBot gateway process in the background

When to use: After installing or after your server reboots

zoarkbot start

Gracefully stops the gateway process

When to use: To shut down ZoarkBot without deleting data

zoarkbot stop

Stops then starts the gateway. Also reloads your config file.

When to use: After editing zoarkbot.json, after updates, or when something seems stuck

zoarkbot restart

Shows gateway health: running/stopped, channel connections, active sessions, config state

When to use: First thing to run when something is wrong

zoarkbot status
zoarkbot status --all   # more detail
zoarkbot status --deep  # includes channel probes

Prints your gateway access token. Paste this into Mission Control to connect.

When to use: When logging in to mc.zoarkai.org for the first time, or after a token change

zoarkbot token

Streams live logs from the gateway. Shows agent activity, errors, and events.

When to use: Debugging issues, or watching agent activity in real-time

zoarkbot logs
zoarkbot logs --follow  # tail -f style

Interactive first-time setup wizard. Creates ~/.zoarkbot/zoarkbot.json with your answers.

When to use: Only during initial installation

zoarkbot setup

Updates ZoarkBot to the latest version. Pulls new binary/package and restarts.

When to use: To get new features and bug fixes. Check mc.zoarkai.org for release notes.

zoarkbot update

These env vars affect all commands:

ZOARKBOT_GATEWAY_TOKENAuth token for the gateway. Same as gateway.auth.token in config.

ZOARKBOT_GATEWAY_PORTOverride the gateway port (default: 18789).

ZOARKBOT_CONFIG_PATHOverride the config file path (default: ~/.zoarkbot/zoarkbot.json).

ANTHROPIC_API_KEYYour Anthropic API key. Can also go in ~/.zoarkbot/.env.

ZOARKBOT_SKIP_LICENSESet to 1 to bypass license check (for development only).