CLI Commands

Complete reference for all ZERG CLI commands. The CLI is a standalone LuaJIT binary (321KB) with zero Python dependency.

Global Flags

All commands accept these flags:

Flag	Description
`--json`	Output raw JSON
`--token <token>`	Override auth token
`--profile <name>`	Use named profile
`--api-url <url>`	Override server URL
`--format <fmt>`	Output format (`text` or `json`)
`--quiet`	Suppress non-essential output
`--version`	Print version
`--help`	Show help

Infrastructure

status

Show server health and status.

bash

zerg status
zerg status --format json

discover

Scan for available models and register them.

bash

zerg discover

show

Display details for a specific model.

bash

zerg show <model-name>

metrics

Fetch Prometheus-format metrics from the server.

bash

zerg metrics

Models & Inference

list

List all discovered models and their status.

bash

zerg list
zerg list --json

models

Alias for list. Show available models.

bash

zerg models

start

Start an inference instance.

bash

zerg start --model glm-5.1
zerg start --model glm-5.1 --gpu-layers 99 --ctx-size 4096

Flag	Description
`--model <name>`	Model to start (required)
`--gpu-layers <n>`	GPU layers to offload
`--ctx-size <n>`	Context window size
`--threads <n>`	CPU threads

stop

Stop a running inference instance.

bash

zerg stop --model glm-5.1

stop-all

Stop all running inference instances.

bash

zerg stop-all

prepare

Download and prepare model files.

bash

zerg prepare --model glm-5.1

Workers

ps

List running worker processes.

bash

zerg ps

spawn

Spawn a new worker process.

bash

zerg spawn --agent build
zerg spawn --model glm-5.1

Flag	Description
`--agent <mode>`	Agent mode (build, plan, explore, review, general, coordinate)
`--model <name>`	Model for the worker

kill

Kill a running worker process.

bash

zerg kill <worker-id>

agents

List available agent modes and their descriptions.

bash

zerg agents

Chat & Conversations

chat

Start an interactive chat session.

bash

zerg chat
zerg chat --model glm-5.1
zerg chat --no-stream

Flag	Description
`--model <name>`	Model to use
`--no-stream`	Disable streaming output
`--stream`	Enable streaming output
`--temp <f>`	Temperature
`--top-p <f>`	Top-p sampling
`--max-tokens <n>`	Maximum output tokens

run

Send a single prompt and print the response.

bash

zerg run "Explain this function"
zerg run --model glm-5.1 "What is OTP?"

Tasks

task

Get task status or list tasks.

bash

zerg task <task-id>

task-cancel

Cancel a running task.

bash

zerg task-cancel <task-id>

task-status

Get detailed task status.

bash

zerg task-status <task-id>

Workflows

workflow list

List all workflows.

bash

zerg workflow list

workflow start

Start a new workflow from a template.

bash

zerg workflow start --template code-review
zerg workflow start --template deploy --model glm-5.1

workflow show

Show workflow details and current state.

bash

zerg workflow show <workflow-id>

workflow cancel

Cancel a running workflow.

bash

zerg workflow cancel <workflow-id>

workflow branch

Create a branch in a workflow.

bash

zerg workflow branch <workflow-id> --name "parallel-analysis"

workflow tree

Display the workflow step tree.

bash

zerg workflow tree <workflow-id>

workflow lineage

Show workflow execution lineage.

bash

zerg workflow lineage <workflow-id>

Background Workers

bg-workers start

Start a background worker.

bash

zerg bg-workers start --agent build --prompt "Refactor the auth module"

bg-workers list

List all background workers.

bash

zerg bg-workers list

bg-workers status

Show background worker status.

bash

zerg bg-workers status <worker-id>

bg-workers logs

Stream background worker logs.

bash

zerg bg-workers logs <worker-id>
zerg bg-workers logs <worker-id> --follow

bg-workers kill

Kill a background worker.

bash

zerg bg-workers kill <worker-id>

Scheduler

schedule list

List all scheduled jobs.

bash

zerg schedule list

schedule add

Create a new scheduled job.

bash

zerg schedule add --cron "0 */6 * * *" --prompt "Run health check"
zerg schedule add --every 3600 --prompt "Sync models"

Flag	Description
`--cron <expr>`	Cron expression
`--every <seconds>`	Interval in seconds
`--at <timestamp>`	One-time execution
`--prompt <text>`	Task prompt
`--model <name>`	Model to use
`--ttl <seconds>`	Job time-to-live

schedule show

Show job details.

bash

zerg schedule show <job-id>

schedule pause

Pause a scheduled job.

bash

zerg schedule pause <job-id>

schedule unpause

Resume a paused job.

bash

zerg schedule unpause <job-id>

schedule run

Trigger a scheduled job immediately.

bash

zerg schedule run <job-id>

schedule delete

Delete a scheduled job.

bash

zerg schedule delete <job-id>

Cluster

cluster

List cluster nodes.

bash

zerg cluster

catalog

Show the global service catalog.

bash

zerg catalog

join

Join a cluster node.

bash

zerg join <node@host>

leave

Leave the cluster.

bash

zerg leave

Channels & Skills

channels

List communication channels.

bash

zerg channels

channel-add

Create a channel.

bash

zerg channel-add --name "alerts"

channel-remove

Remove a channel.

bash

zerg channel-remove <channel-id>

channel-test

Test channel connectivity.

bash

zerg channel-test <channel-id>

channel-send

Send a message to a channel.

bash

zerg channel-send <channel-id> --message "Deploy complete"

skills

List registered skills.

bash

zerg skills

skill-search

Search for skills.

bash

zerg skill-search "code review"

skill-register

bash

zerg skill-register --name "my-skill" --description "Custom skill"

skill-remove

Remove a registered skill.

bash

zerg skill-remove <skill-id>

Recipes

recipe-list

List available recipes.

bash

zerg recipe-list

recipe-show

Show recipe details.

bash

zerg recipe-show <recipe-name>

recipe-run

Execute a recipe.

bash

zerg recipe-run <recipe-name>

recipe-reload

Reload recipe definitions.

bash

zerg recipe-reload

Circuits & Plugins

circuits

List circuit breaker states.

bash

zerg circuits

circuits-reset

Reset all circuit breakers.

bash

zerg circuits-reset

plugin-eval

Evaluate a Lua expression in the plugin sandbox.

bash

zerg plugin-eval "return 1 + 1"

plugin-workers

List plugin-managed workers.

bash

zerg plugin-workers

plugin-spawn

Spawn a plugin worker.

bash

zerg plugin-spawn --plugin <name>

ZMQ

zmq-workers

List ZMQ-connected workers.

bash

zerg zmq-workers

zmq-dispatch

Dispatch a task to a ZMQ worker.

bash

zerg zmq-dispatch --prompt "Analyze this log" --worker <worker-id>

zmq-status

Show ZMQ gateway status.

bash

zerg zmq-status

Authentication

Authenticate with a ZERG server.

bash

zerg login --url https://api.nonsense.ws --token <token>

logout

Clear authentication credentials.

bash

zerg logout

keyring-test

Test keyring access.

bash

zerg keyring-test

keyring-set

Store a secret in the OS keyring.

bash

zerg keyring-set --key zerg-token --value <token>

keyring-get

Retrieve a secret from the OS keyring.

bash

zerg keyring-get --key zerg-token

keyring-delete

Delete a secret from the OS keyring.

bash

zerg keyring-delete --key zerg-token

Update

update check

Check for CLI updates.

bash

zerg update check

update download

Download a new version.

bash

zerg update download

update apply

Apply a downloaded update.

bash

zerg update apply

update rollback

Rollback to the previous version.

bash

zerg update rollback

Shell Completion

completion

Generate shell completion scripts.

bash

zerg completion bash >> ~/.bashrc
zerg completion zsh > ~/.zfunc/_zerg
zerg completion fish > ~/.config/fish/completions/zerg.fish

See Shell Completion for detailed setup instructions.

CLI Commands ​

Global Flags ​

Infrastructure ​

status ​

discover ​

show ​

metrics ​

Models & Inference ​

list ​

models ​

start ​

stop ​

stop-all ​

prepare ​

Workers ​

ps ​

spawn ​

kill ​

agents ​

Chat & Conversations ​

chat ​

run ​

Tasks ​

task ​

task-cancel ​

task-status ​

Workflows ​

workflow list ​

workflow start ​

workflow show ​

workflow cancel ​

workflow branch ​

workflow tree ​

workflow lineage ​

Background Workers ​

bg-workers start ​

bg-workers list ​

bg-workers status ​

bg-workers logs ​

bg-workers kill ​

Scheduler ​

schedule list ​

schedule add ​

schedule show ​

schedule pause ​

schedule unpause ​

schedule run ​

schedule delete ​

Cluster ​

cluster ​

catalog ​

join ​

leave ​

Channels & Skills ​

channels ​

channel-add ​

channel-remove ​

channel-test ​

channel-send ​

skills ​

skill-search ​

skill-register ​

skill-remove ​

Recipes ​

recipe-list ​

recipe-show ​

recipe-run ​

recipe-reload ​

Circuits & Plugins ​

circuits ​

circuits-reset ​

plugin-eval ​

plugin-workers ​

plugin-spawn ​

ZMQ ​

zmq-workers ​

zmq-dispatch ​

zmq-status ​

Authentication ​

login ​

CLI Commands

Global Flags

Infrastructure

status

discover

show

metrics

Models & Inference

list

models

start

stop

stop-all

prepare

Workers

ps

spawn

kill

agents

Chat & Conversations

chat

run

Tasks

task

task-cancel

task-status

Workflows

workflow list

workflow start

workflow show

workflow cancel

workflow branch

workflow tree

workflow lineage

Background Workers

bg-workers start

bg-workers list

bg-workers status

bg-workers logs

bg-workers kill

Scheduler

schedule list

schedule add

schedule show

schedule pause

schedule unpause

schedule run

schedule delete

Cluster

cluster

catalog

join

leave

Channels & Skills

channels

channel-add

channel-remove

channel-test

channel-send

skills

skill-search

skill-register

skill-remove

Recipes

recipe-list

recipe-show

recipe-run

recipe-reload

Circuits & Plugins

circuits

circuits-reset

plugin-eval

plugin-workers

plugin-spawn

ZMQ

zmq-workers

zmq-dispatch

zmq-status

Authentication

login