CLI reference

The hubzoid command is installed with the package. python -m hubzoid runs the same CLI, which is useful from a source checkout. Every command accepts --help.

ConventionsCopy Anchor Link

• A Hub path argument defaults to . (the current directory) unless the usage line shows it as required. Paths resolve against the directory you run the command from.
• The Hub's .env is loaded by the commands that build or serve the Hub, and it wins over variables already set in your shell. See configuration.
• Commands that change access or runs (grant, revoke, schedule pause, schedule resume, schedule cancel, backup) record the operator as the actor, for example cli:alice or cli:alice@build-host.
• Exit code 0 means success. Where a command defines other codes, they are listed with the command.

Command indexCopy Anchor Link

Create a HubCopy Anchor Link

hubzoid initCopy Anchor Link

Scaffold a new Hub folder from a bundled template.

hubzoid init [NAME] [--template minimal|demo|watchtower] [--model MODEL] [--force]

What it writes:

• Every file of the template into the Hub folder. Existing files are skipped unless you pass --force. Runtime state (.hubzoid/, .openwebui-data/) is never copied.
• A .env with a random BRIDGE_API_KEYS value, created with mode 0600. MODEL is --model when given. Otherwise, in an interactive terminal on a new Hub, Hubzoid detects authenticated local claude and codex logins, uses the only one it finds, or asks once when both are usable. Without either, MODEL=claude-local.
• When the parent folder looks new (empty, or holding only dotfiles, README.md, requirements.txt, LICENSE, LICENSE.md or .env), a repository wrapper in the parent: requirements.txt pinned to the installed Hubzoid version, .gitignore and README.md. Existing parent files are never overwritten, even with --force.

Run hubzoid init again in the same parent to add another Hub beside the first. An unknown template name exits with code 2 and lists the templates that exist. See templates.

hubzoid new workflowCopy Anchor Link

Scaffold workflows/<name>/main.py with a runnable example workflow.

hubzoid new workflow NAME [HUB_DIR]

The generated file declares a manual workflow with @workflow(), reads and writes hub.state, and performs a side effect in a @step. It needs no model or outside service. The command prints the hubzoid schedule run line that runs it once. Add a schedule and timezone after you have tested its effects. The command exits with code 1 if the folder already exists. See code workflows.

ServeCopy Anchor Link

hubzoid runCopy Anchor Link

Start one Hub: the bridge, the web chat (Open WebUI), the public edge and any surfaces you ask for.

hubzoid run [HUB] [--port N] [--bridge-port N] [--host ADDR] [--no-ui] [--slack] [--whatsapp] [--telegram] [--webhook]

What starts, in order:

1. The bridge on 127.0.0.1:<bridge-port>. The command waits up to 60 seconds for /healthz and exits with code 1 if the bridge does not come up.
2. The web chat on a loopback port. By default this is the public port plus 40000 (or plus 1 when that would pass 65000). HUBZOID_OWUI_PORT overrides it.
3. The edge on <host>:<port>. It forwards /artifacts and /portal to the bridge, /mcp when MCP_SERVER=true, /webhooks/<hub> when an inbound surface is enabled, and everything else to the web chat.
4. The Slack adapter and the inbound receiver as child processes, when requested and configured.

With HUBZOID_DISABLE_EDGE=1, no edge runs and the web chat binds the public port itself. Ctrl+C stops every child process. The command exits with code 2 when the Hub folder or its AGENTS.md is missing. See architecture and single server.

hubzoid gatewayCopy Anchor Link

Run one shared web chat over several Hubs, with one headless bridge per Hub.

hubzoid gateway HUB [HUB ...] [--port N] [--host ADDR] [--public-url URL] [--name NAME] [--data-dir DIR] [--launch-bridges | --no-bridges]

Behavior worth knowing:

• The gateway writes <data-dir>/deployment.json. Bridges and operator commands discover it, so a hubzoid grant run in any Hub folder lands in the store the gateway reads.
• All bridges share one operational database, sqlite:///<data-dir>/hubzoid-operational.db, unless HUBZOID_OPERATIONAL_DB or DATABASE_URL is set. Workflow engine databases stay per Hub. A multi-Hub gateway refuses a SQLite HUBZOID_DBOS_DB.
• Each bridge runs as hubzoid run <hub> --no-ui with scheduled code workflows enabled.
• Downloads route through /b/<hub>/artifacts, MCP through /b/<hub>/mcp for Hubs with MCP_SERVER=true, and the Console through /portal.
• With HUBZOID_GATEWAY_ADMIN_EMAIL, HUBZOID_GATEWAY_ADMIN_PASSWORD and WEBUI_AUTH=true, each Hub's model entry and team group are provisioned in the web chat at boot.

See gateway deployment.

hubzoid slackCopy Anchor Link

Slack chat surface. The adapter uses Socket Mode, so it needs no public URL.

hubzoid slack run [HUB]
hubzoid slack manifest [HUB] [--format json|yaml]
hubzoid slack systemd [HUB] [--user USER] [--python PATH]

See Slack.

hubzoid inboundCopy Anchor Link

The receiver for WhatsApp, Telegram and the generic webhook.

hubzoid inbound run [HUB]
hubzoid inbound systemd [HUB] [--user USER] [--python PATH]

hubzoid run --whatsapp, --telegram or --webhook starts the same receiver for you. See WhatsApp and Telegram and webhooks.

Test and checkCopy Anchor Link

hubzoid testCopy Anchor Link

Send one prompt to the Hub's agent and print the reply. Runs in process, with no bridge or web chat.

hubzoid test [HUB] [--prompt TEXT] [--file PATH ...]

The backend follows the Hub's model: claude-local runs on the Claude Agent SDK, codex-local on local Codex, and anything else on the OpenAI Agents SDK. With --file, uploads and artifacts live in <hub>/.hubzoid/chats/cli-test/. A file larger than HUBZOID_MAX_UPLOAD_BYTES exits with code 2 before the model is called.

hubzoid doctorCopy Anchor Link

Check a Hub and its deployment. Read only.

hubzoid doctor [HUB] [--json] [--skip-secret-fetch]

Exit codes: 0 when no check fails, 1 when any check fails, 2 when the Hub folder does not exist. Every check id is described in the doctor reference.

hubzoid evalCopy Anchor Link

Run the Hub's eval cases from evals/*.md and inspect results.

hubzoid eval run [HUB] [--tag TAG] [--case GLOB] [--no-judge] [--judge-model MODEL] [--model MODEL] [--compare] [--quiet]
hubzoid eval list [HUB]
hubzoid eval status [HUB]
hubzoid eval explain HUB CASE

See evals.

Schedules and runsCopy Anchor Link

hubzoid scheduleCopy Anchor Link

Inspect and control markdown tasks (schedule/*.md) and code workflows (workflows/<name>/*.py). Scheduled work fires inside the running bridge. These commands inspect it and act on it.

hubzoid schedule list [HUB]
hubzoid schedule status [HUB]
hubzoid schedule run HUB TASK [--timeout SECONDS] [--max-rounds N] [--model MODEL] [--dry-run]
hubzoid schedule pause HUB NAME
hubzoid schedule resume HUB NAME
hubzoid schedule cancel HUB RUN_ID

schedule run looks for a markdown task named TASK first. It runs on the Hub's workflow engine on the same one-at-a-time markdown queue as scheduled fires, so it never overlaps a scheduled run, and it ignores the cron and the idle gate. When no markdown task matches, it looks for a code workflow by folder or function name (hyphens and underscores are interchangeable) and runs it.

Exit codes for schedule run: 0 when the task reported done or the workflow returned, 1 when the run failed or ended without finishing, 2 when no task or workflow matched or a workflow was given --timeout, --max-rounds or --model. See operating runs and markdown tasks.

AccessCopy Anchor Link

These commands act on the access store for the Hub, or on the shared store of a gateway when the Hub belongs to one. grant and revoke print the store they write to, with any password hidden. See access administration.

hubzoid grantCopy Anchor Link

hubzoid grant SUBJECT PERMISSION [HUB_DIR] [--hub NAME] [--org]

Granting any tool permission also grants use_hub in the same Hub. The wildcard permission * is never grantable. New access for everyone signed in (the subject *) is refused and exits with code 1. An existing one can still be removed with hubzoid revoke '*' use_hub --hub <hub>. Scheduled work runs as an account, so grant the permissions a workflow needs to the account it runs as.

hubzoid revokeCopy Anchor Link

hubzoid revoke SUBJECT PERMISSION [HUB_DIR] [--hub NAME] [--org]

Takes the same arguments as grant. Revoking use_hub removes every permission the subject holds in that Hub. The command refuses to remove the last organization admin and exits with code 1.

hubzoid accessCopy Anchor Link

hubzoid access check SUBJECT [HUB_DIR] [--hub NAME]
hubzoid access list [HUB_DIR] [--hub NAME]
hubzoid access bootstrap [HUB_DIR] [--admin SUBJECT ...] [--authoritative]
hubzoid access migrate [HUB_DIR] [--from-owui URL] [--model-id ID] [--standalone-public] [--apply] [--remigrate]
hubzoid access diff [HUB_DIR] [--from-owui URL] [--model-id ID] [--standalone-public]
hubzoid access rollback BACKUP [HUB_DIR]
hubzoid access sync [HUB_DIR]

migrate --apply refuses to run without model evidence (--from-owui or --standalone-public), refuses an empty plan, writes a snapshot to .hubzoid/backups/access-<id>.json before it changes anything, and exits with code 1 unless the store matches the plan exactly afterwards. It exits with code 2 when the migration is blocked, when effective access would change, or when the Hub is already migrated and --remigrate is absent.

hubzoid auditCopy Anchor Link

Show restricted tool decisions: who called which restricted tool, on which surface, and whether it was allowed.

hubzoid audit [HUB] [--limit N] [--user EMAIL] [--denied]

Each line shows the time, user, ALLOW or DENY, the tool, and the surface with the reason. The Console's Activity page shows the same decisions. See people and activity.

OperationsCopy Anchor Link

hubzoid backupCopy Anchor Link

Save a deployment's databases, chat data and Hub state to one archive while chat keeps working.

hubzoid backup [HUB] [--out PATH] [--include-secrets] [--wait SECONDS]

New scheduled runs are held while the backup runs, and running ones finish first. Hub content (AGENTS.md, skills, knowledge) belongs in Git and is not included. PostgreSQL databases are not included either. The command names each one so you can back it up with pg_dump. The archive holds user accounts and chats, so store it like a secret. Exits with code 1 on error. See backup and restore.

hubzoid restoreCopy Anchor Link

Put a backup back. Stop the Hub or gateway first.

hubzoid restore ARCHIVE [--move OLD=NEW ...] [--dry-run]

Everything returns to its original path unless moved. Whatever is at a target now is kept beside it as <name>.pre-restore-<time>. When database passwords were left out of the saved deployment manifest, the command says so. Start the gateway before any bridge, because hubzoid gateway rewrites that manifest from its environment. Run hubzoid doctor after starting.

hubzoid versionCopy Anchor Link

hubzoid version

Prints the installed Hubzoid version.

Next stepsCopy Anchor Link

Read this page as Markdown