CLI Reference: Every Hubzoid Command

Every hubzoid command and subcommand, with its usage line, options, defaults and exit codes, from hubzoid init and run to doctor and grant.

Every hubzoid command, grouped by task. Each one accepts --help, and a command group run without a subcommand prints its subcommands.

Conventions

hubzoid is installed with the package. python -m hubzoid runs the same CLI from a source checkout.
A Hub argument defaults to . (the current folder) unless the usage line shows it as required. Paths resolve against the folder you run the command in.
Commands that build or serve a Hub load its .env, which wins over variables already set in your shell. See configuration.
Commands that change access, accounts or runs (grant, revoke, admin, schedule run, schedule pause, schedule resume, schedule cancel, backup) record the operator as the actor, for example cli:alice or cli:alice@build-host.
Most commands that read or change records take --json and then print only JSON. Commands that act on a person's records take --user EMAIL and default to the local owner.
Commands that replace a file or record take --expected-revision: the revision you read, or absent to create. A stale revision changes nothing.
Exit code 0 means success. Other codes are listed with each command.

Command index

Task	Commands
Create and run	`init`, `new workflow`, `run`, `status`, `restart`, `reload`, `stop`, `start`, `logs`, `upgrade`, `service install`, `gateway`
Test and check	`test`, `doctor`, `eval`, `hub`
Schedules and work	`schedule`, `work-items`, `operations`, `stations`, `handoffs`, `requests`, `hitl`, `workflow-access`
Accounts and access	`admin`, `auth`, `grant`, `revoke`, `access`, `audit`
Channels and embedding	`channels`, `intake`, `slack`, `inbound`, `embed`
Hub content and limits	`hub-changes`, `workspace`, `knowledge`, `models`, `secrets`, `budgets`, `sandbox`, `apps`, `branding`
Chat records	`chat`, `files`, `artifacts`
Operations	`backup`, `restore`, `deploy`, `migrate`, `api`, `version`

Create and run

hubzoid init

Create a small starter Hub: every folder Hubzoid reads, a sample to try and the model.

Usage

hubzoid init [NAME] [--model MODEL] [--force]

Argument or option	Default	What it does
`NAME`	`demo-hub`	Folder to create under the current folder. An absolute path is used as given. `.` starts a Hub in the current folder.
`--model`		Model for a new Hub, written to `MODEL` in `.env`, for example `codex-local`, `claude-local` or a provider model id.
`--force`	off	Overwrite files that already exist in the Hub folder.

What it writes:

The starter for Kestrel & Oak, a fictional home-goods shop: AGENTS.md, README.md, .gitignore, knowledge/house-rules.md (three house rules), evals/refund-window.md (one check) and connectors/.mcp.json. Existing files are skipped unless you pass --force.
Every folder Hubzoid reads: agents/, connectors/, evals/, knowledge/, raw_data/, schedule/, skills/, tools_local/ and workflows/. An empty folder gets a .gitkeep.
A .env readable only by you, with a random BRIDGE_API_KEYS. MODEL is --model when given. Otherwise, in a terminal on a new Hub, Hubzoid uses a signed-in claude or codex CLI, or asks once when both are signed in. When neither is, it offers to save an OpenRouter, Anthropic or OpenAI key with a matching model. Press Enter to skip. A Claude subscription token is not accepted there: it belongs in CLAUDE_CODE_OAUTH_TOKEN with MODEL=claude-local. Outside a terminal (scripts, CI, image builds) it never prompts and keeps MODEL=claude-local.
When the parent folder looks new (empty, or only dotfiles, README.md, requirements.txt, LICENSE, LICENSE.md or .env), an agents-repo wrapper in the parent: requirements.txt pinned to the installed Hubzoid, .gitignore and README.md. Parent files are never overwritten, even with --force.

Run hubzoid init again in the same parent to add another Hub beside the first. The command ends by printing the clone lines of the ready-to-use Hubs. See templates.

Exit codes: 2 when --template is given. Templates are no longer bundled: the command says where the named one went, creates nothing and prints the ready-to-use Hubs.

hubzoid new workflow

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

Usage

hubzoid new workflow NAME [HUB_DIR]

Argument	Default	What it does
`NAME`	required	Workflow folder name, for example `review-prs`. The function name is the name with hyphens turned into underscores.
`HUB_DIR`	`.`	Hub folder.

The 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 time zone after you have tested its effects. See code workflows.

Exit codes: 1 when the folder already exists.

hubzoid run

Start a deployment: each Hub's bridge in its own supervised process, and on one public port the web app (chat at /, Settings at /settings, sign-in at /auth), file downloads and hosted MCP.

Usage

hubzoid run [HUBS...] [--port N] [--bridge-port N] [--host ADDR] [--data-dir DIR] [--no-open]

Argument or option	Default	What it does
`HUBS`	`hubzoid.yaml` here, else `.`	Hub folders. Each must contain `AGENTS.md`, and folder names must be unique, ignoring case. The first Hub also answers at `/`.
`--port`	`PORT`, else `3080`	Public port for the web app, downloads and MCP.
`--bridge-port`	`BRIDGE_PORT`, else the first free port from `8000`	One Hub only: its bridge port on `127.0.0.1`. In a `hubzoid.yaml` deployment, set `BRIDGE_PORT` in a Hub's `.env` instead.
`--host`	`127.0.0.1`	Interface the public port binds to. Also read from `HUBZOID_HOST`. `0.0.0.0` exposes it on the network, which needs sign-in. The bridge always stays on `127.0.0.1`.
`--data-dir`	`.hubzoid` next to `hubzoid.yaml`	State folder of a deployment of several Hubs: manifest, shared database, keys and logs.
`--no-open`	off	Do not open the web app in a browser. It opens only from a terminal, on a loopback host.

What starts, in order:

Each Hub's bridge on its own 127.0.0.1 port. A busy port is skipped unless you chose it. The command waits for /healthz, up to three minutes on a slow first start. A bridge that stops or does not come up is tried again, and hubzoid logs <hub> shows why.
The public port on <host>:<port>. It forwards every path to the bridge, except /webhooks/<hub>, which goes to the inbound receiver when a channel file turns on WhatsApp, Telegram or the generic webhook. Named webhooks from workflows/settings.yaml (/webhooks/<hub>/<name>) go to the bridge. /v1/chat/completions and /v1/models pass with a personal API key. The bridge's other /v1 paths, /uploads and /otel answer 404 on the public port.
Each Hub's channels, from the files in its channels/ folder. A channel runs and restarts with its Hub. A channel whose settings are missing from the Hub's .env stays off, and the start names what is missing.

When it is ready, the command prints one line with the address and whether sign-in is on, then opens the browser unless --no-open is given:

Output

✓ Hubzoid is ready: http://127.0.0.1:3080  (local mode, sign-in off)
  Connect Claude Code: claude mcp add --transport http my-hub http://127.0.0.1:3080/mcp

Hosted MCP is on by default for a loopback host or an https HUBZOID_PUBLIC_URL, and the command then prints the claude mcp add line. MCP_SERVER in the Hub's .env or the environment wins. Ctrl+C stops every child process.

Restarts. A Hub that exits is started again after 1 second, then after waits that double up to 60 seconds, while the other Hubs keep answering. After 5 failed starts in 10 minutes it is marked failed until hubzoid start <hub>, and its pages answer 503.

Sign-in. Sign-in is off by default (local mode: whoever opens the page is the Hub's owner). With sign-in off, a --host that is not a loopback address is refused unless HUBZOID_ALLOW_UNAUTHENTICATED_NETWORK=true. Turn sign-in on with sign_in: true in hubzoid.yaml or HUBZOID_AUTH=true, and create the first administrator with HUBZOID_ADMIN_EMAIL and HUBZOID_ADMIN_PASSWORD, or with hubzoid admin create.

Schedules. Markdown tasks and scheduled evals fire whenever their files exist, unless HUBZOID_DISABLE_SCHEDULE=1. Code workflows fire on their schedule only with HUBZOID_SCHEDULES=1, and always in a deployment that hubzoid run starts from hubzoid.yaml or with several Hubs.

Several Hubs, or a hubzoid.yaml:

Every bridge shares the operational store (accounts, sessions, conversations and access), so one sign-in covers every agent a person may use. The edge sends /b/<slug>/api, /b/<slug>/artifacts, /b/<slug>/mcp and /b/<slug>/branding to that Hub's bridge and everything else to the first bridge.
Deployment settings (public_url, sign_in, owner, in_app_editing, brand, chat, apps) live in hubzoid.yaml, and its secrets in the .env next to it. A Hub .env that sets a different HUBZOID_AUTH, or its own HUBZOID_SECRET_KEY, stops the start. See configuration.
The deployment writes <data-dir>/deployment.json. Bridges and operator commands find it, so hubzoid grant or hubzoid admin run in any Hub folder reach the store the deployment reads.
The deployment key (<data-dir>/secret.key, or HUBZOID_SECRET_KEY) is created before the bridges start and its fingerprint is printed. Back it up apart from the data.
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 SQLite HUBZOID_DBOS_DB is refused.
The page chrome comes from HUBZOID_GATEWAY_BRANDING (a Hub slug or a path), then a populated <data-dir>/branding/, then the first Hub's branding/. Each agent keeps its own name and avatar.

Exit codes:

Code When

1 The public port is in use, or a bridge port you chose is in use.

2 A Hub folder or its AGENTS.md is missing, two Hub folders share a name, hubzoid.yaml is invalid or lists no Hubs, the bridge and public ports are the same, --bridge-port is given for several Hubs, a Hub's settings disagree with its deployment, sign-in is off on a non-loopback host, or an old channel flag such as --slack is given. Channels now turn on with a file in the Hub's channels/ folder, and the error prints that file.

Code	When
`1`	The public port is in use, or a bridge port you chose is in use.
`2`	A Hub folder or its `AGENTS.md` is missing, two Hub folders share a name, `hubzoid.yaml` is invalid or lists no Hubs, the bridge and public ports are the same, `--bridge-port` is given for several Hubs, a Hub's settings disagree with its deployment, sign-in is off on a non-loopback host, or an old channel flag such as `--slack` is given. Channels now turn on with a file in the Hub's `channels/` folder, and the error prints that file.

See architecture, single server and several Hubs.

Control a running deployment

These act on a running hubzoid run. Run them in its folder, or pass --data-dir. Name a Hub by its folder name or slug.

Usage

hubzoid status [--data-dir DIR] [--json]
hubzoid restart HUB [HUB ...] [--grace SECONDS] [--data-dir DIR] [--json]
hubzoid reload HUB [HUB ...] [--grace SECONDS] [--data-dir DIR] [--json]
hubzoid stop HUB [HUB ...] [--grace SECONDS] [--data-dir DIR] [--json]
hubzoid start HUB [HUB ...] [--data-dir DIR] [--json]
hubzoid logs HUB [--lines N] [--follow] [--data-dir DIR]

Command	What it does
`status`	Each Hub's state, restarts, last exit and whether it needs a reload.
`restart`	Restarts Hubs one after the other, each drained first. The others keep running.
`reload`	Checks the Hub's folder, then restarts it so every change takes effect. A folder with problems changes nothing.
`stop`	Stops Hubs, drained first, until `hubzoid start`.
`start`	Starts stopped or failed Hubs again.
`logs`	A Hub's recent output from its log file, including its channels. `edge` shows the front door. `-n` sets the number of lines (default `200`) and `-f` keeps printing new ones.

Draining gives running work --grace seconds to finish, 120 by default. Each command exits with code 1 when the deployment cannot be reached or the change fails.

hubzoid upgrade

Move a deployment to one run mode, once and offline, after hubzoid backup. It writes every setting kept only in the database into its file (hubzoid.yaml, branding/, connectors/, .env, channel files), exports Workspace drafts, then brings the database to the current schema.

Usage

hubzoid upgrade [FOLDER] [--data-dir DIR] [--hub PATH ...] [--dry-run]

Argument or option	Default	What it does
`FOLDER`	`.`	The deployment folder: `hubzoid.yaml`, a Hub, or where `hubzoid gateway` ran.
`--data-dir`	found from the folder	The state folder, for example a gateway's `--data-dir`.
`--hub`		Hub folders, when there is no `hubzoid.yaml` or manifest. Repeatable.
`--dry-run`	off	Say what would be written and change nothing.

It never overwrites a file and never prints a secret. Review the result with git diff, then start with hubzoid run. Exit codes: 2 when no Hubs are found or the deployment is still running, 1 when the upgrade stops. See upgrading.

hubzoid service install

Print or write one systemd unit for the whole deployment.

Usage

hubzoid service install [FOLDER] [--port N] [--host ADDR] [--data-dir DIR] [--user NAME] [--write]

Argument or option	Default	What it does
`FOLDER`	`.`	The deployment folder: the one holding `hubzoid.yaml`, or a Hub.
`--port`	`3080`	Public port.
`--host`	`127.0.0.1`	Interface the public port binds to.
`--data-dir`		State folder, when it is not the default.
`--user`	root	Linux user the service runs as.
`--write`	off	Write `/etc/systemd/system/hubzoid.service` instead of printing the unit.

The unit runs hubzoid run --no-open in the folder with Restart=always, KillMode=mixed and TimeoutStopSec=180. Enable it with systemctl daemon-reload && systemctl enable --now hubzoid. Restart one Hub with hubzoid restart <hub>, not the whole service. Exits with code 1 when --write cannot write the file. See single server.

hubzoid gateway

An alias of hubzoid run for several Hubs, kept until the next release. It prints the hubzoid.yaml that describes the same deployment, then runs it. Save that file next to the Hub folders and use hubzoid run from then on.

Usage

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

Argument or option	Default	What it does
`HUB`	required	Hub folders to serve behind one front door.
`--port`	`PORT`, else `3080`	Public port.
`--host`	`127.0.0.1`	Interface the public edge binds to. Also read from `HUBZOID_HOST`.
`--public-url`	`HUBZOID_PUBLIC_URL`	Public base URL, for example `https://hub.example.com`. Used for each Hub's download links.
`--name`	`Hubzoid`	Display name of the deployment.
`--data-dir`	`./.hubzoid-gateway`	State folder for the manifest, the shared database and the deployment key.

--no-bridges exits with code 2: hubzoid run supervises every Hub, and hubzoid restart <hub> restarts one. See several Hubs.

Test and check

hubzoid test

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

Usage

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

Argument or option	Default	What it does
`HUB`	`.`	Hub folder.
`--prompt`	`Reply with the single word: pong`	The prompt to send.
`--file`, `-f`		Attach a local file. Repeatable. Files are staged into the `cli-test` chat so the agent reads them with `read_upload`, or sees them directly when they are images.
`--json`	off	Print only JSON: the reply, each tool call and any errors.

The backend follows the Hub's model: claude-local runs on the Claude Agent SDK, codex-local on local Codex, anything else on the OpenAI Agents SDK. With --file, uploads and artifacts live in <hub>/.hubzoid/chats/cli-test/. Exit codes: 2 when a file is larger than HUBZOID_MAX_UPLOAD_BYTES (checked before the model is called), 1 when --json reports an error.

hubzoid doctor

Check a Hub and its deployment: files, configuration layers and secrets, agent build, schedules, schema, sign-in, exposure, model credentials, backups and scheduled work. Read only.

Usage

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

Argument or option	Default	What it does
`HUB`	`.`	Hub folder.
`--json`	off	Print the checks as JSON with stable check ids.
`--skip-secret-fetch`	off	Do not call AWS Secrets Manager. Named secrets are listed but not read.

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

hubzoid eval

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

Usage

hubzoid eval run [HUB] [--tag TAG] [--case GLOB] [--no-judge] [--judge-model MODEL] [--model MODEL] [--run-as EMAIL] [--details] [--compare] [--quiet] [--junit PATH] [--json]
hubzoid eval list [HUB] [--json]
hubzoid eval status [HUB] [--json]
hubzoid eval explain HUB CASE [--json]

Subcommand	What it does
`run`	Runs the selected cases through the Hub's own runtime, with the same model, tools, MCP servers and access guard as chat, and writes a results file under `.hubzoid/evals/`. Free checks run first. A case with a `## Criteria` section is then graded by the judge, only when the free checks passed. With `CI=true` the run is recorded as a CI run.
`list`	Each case with its checks, turns, tags, account and schedule.
`status`	The last run, its pass rate, the model and judge, and the cases failing now.
`explain`	For one case of the last run: the case file, the prompt or each turn, the full response, the tool calls with their arguments and a preview of each result, each check's verdict and the judge's score and reasoning.

Options of eval run:

Option	Default	What it does
`--tag`		Only cases carrying this tag.
`--case`		Only cases whose name matches this glob, for example `refund-*`.
`--no-judge`	off	Skip the grading call. The agent still runs, so this is cheaper, not free.
`--judge-model`	`HUBZOID_EVAL_JUDGE_MODEL`, else the Hub's model	Model that grades. Pin it for stable scores.
`--model`		Override the model under test for this run.
`--run-as`		Run the cases as this account email, with the same rules as a workflow identity. A case with its own `run_as` keeps it. Grants nothing.
`--details`	off	Under each case, one line per tool call with its key arguments, whether it succeeded and how long it took.
`--compare`	off	Also show what changed since the previous run.
`--quiet`, `-q`	off	Print only the summary and failures.
`--junit`		Also write a JUnit XML report to this file, for CI.
`--json`	off	Print only JSON, the same record as the results file.

CASE is the case id: its path under evals/ without .md.

Output

1 case(s) · my-hub
judge: claude-local (hub default — pin it for stable scores)
  ✓ refund-window

case                 judge         time  reason
refund-window  PASS  10/10         5.3s

1 passed of 1

Exit codes for run: 1 when any case fails, 2 when a case file cannot be parsed or --run-as is not a valid email, 0 when there are no cases or none match. explain exits with code 1 when there is no run yet and 2 when the case was not in the last run. See evals.

hubzoid hub

A Hub's declared settings (settings.yaml, hub.settings.yaml) and its own checks (hub.manifest.yaml).

Usage

hubzoid hub settings [HUB] [--schema] [--json]
hubzoid hub configure [HUB] [--file PATH] [--check | --apply] [--expected-revision REV] [--json]
hubzoid hub doctor [HUB] [--check ID ...] [--json]

Subcommand	What it does
`settings`	Declared settings with their values and sources. Secrets show their reference only. `--schema` shows the declarations only.
`configure`	Checks a values file (default: the Hub's `hub.settings.yaml`) and shows the changes. `--apply` writes it to the Hub.
`doctor`	The Hub's own checks: its settings and the checks in `hub.manifest.yaml`. `hubzoid doctor` runs these with everything else. `--check` runs one check, repeatable.

Schedules and work

hubzoid schedule

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.

Usage

hubzoid schedule list [HUB] [--json]
hubzoid schedule status [HUB] [--json]
hubzoid schedule run HUB TASK [--timeout SECONDS] [--max-rounds N] [--model MODEL] [--input KEY=VALUE ...] [--dry-run]
hubzoid schedule pause HUB NAME
hubzoid schedule resume HUB NAME
hubzoid schedule cancel HUB RUN_ID
hubzoid schedule deliveries [HUB] [--json]
hubzoid schedule redrive EVENT_ID [--hub HUB]

Subcommand	What it does
`list`	One line per code workflow and markdown task (as `md:<task>`) with state, time zone, next run and the account it runs as, or `cannot run:` with the fix. Then markdown tasks with their cron in words, next fire time, last result and flags (script, model, commit, push). Webhook tasks show their trigger. Exits with code `1` when any task file is invalid.
`status`	Code workflow state, next run and missed slots, the 20 most recent runs with status and duration, and each markdown task's first seen, last fired, last result and last run log.
`run`	Fires one task or workflow now. See below.
`pause`	Stops scheduled runs of one markdown task or code workflow until resumed. Queued or running runs continue (use `cancel`). Manual runs still work. Recorded in the access audit.
`resume`	Resumes scheduled runs. A markdown task that became due while paused runs once. Code workflows do not back-fill missed slots.
`cancel`	Cancels a queued or running run by id. The run stops at its next step boundary. Work already done, such as a sent message or a pushed commit, is not undone. Recorded in the access audit.
`deliveries`	The Hub's 50 newest webhook events and 50 newest alert deliveries, each with id, state, attempt and error. Payloads, headers and digests are never shown.
`redrive`	Retries one failed webhook event by its id (`wh:...`). Check first what its earlier attempts already did outside Hubzoid, because the retry runs the workflow again. Exits with code `1` unless the id is a failed event of this Hub.

schedule run looks for a markdown task named TASK first, then a code workflow by its function name (hyphens read as underscores). A markdown task runs on the same one-at-a-time queue as scheduled fires, so it never overlaps a scheduled run, and it ignores the cron and the idle gate. A code workflow starts as a team run recorded as started from the CLI. When the Hub's bridge is running, the run goes to its workflow engine. When the run publishes a report, the command prints its link.

Option of `schedule run`	Applies to	What it does
`--timeout`	markdown tasks	Override the per-round timeout in seconds.
`--max-rounds`	markdown tasks	Override the round cap.
`--model`	markdown tasks	Override the model, for example `claude-local/opus`. Ignored with a warning for `run: script` tasks.
`--input`	code workflows	One input as `key=value`, checked against the inputs the workflow declares. Repeat for each input.
`--dry-run`	both	Print the first-round prompt or the script command and stop. For a code workflow, say which workflow would run without running any code.

Output

✓ done in 1 round(s): Published "Monday brief" (support hours, 30-day refund window, $500
large-order approval) from knowledge/house-rules.md.

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 nothing matched, the workflow does not load, a workflow was given --timeout, --max-rounds or --model, a markdown task was given --input, or an input is invalid. pause and resume exit with code 2 when the name matches nothing, and cancel with code 1 when the run id is unknown. See operating runs, markdown tasks and webhooks.

hubzoid work-items

Durable work items: work with a stable key that survives restarts and never runs a finished stage twice.

Usage

hubzoid work-items validate|config [HUB] [--json]
hubzoid work-items start [HUB] --workflow NAME --key KEY [--route ROUTE] [--input FILE] [--new-generation] [--as EMAIL] [--json]
hubzoid work-items list [HUB] [--state STATE] [--workflow NAME] [--limit N] [--json]
hubzoid work-items show|message|cancel|resume|restart [HUB] ITEM_ID [options]

Subcommand	What it does
`validate`	Checks `work-items.yaml` and every workflow's routes without running anything.
`start`	Starts durable work. The same key and input returns the existing item. `--input` is a JSON file, or `-` for standard input.
`list`	Work items, newest first. `--limit` defaults to `50`.
`show`	One work item: stages, operations, state and result.
`message`	Sends a follow-up (`--text`) to active work. It is read at the next stage boundary.
`cancel`	Cancels work. Partial output and the record of what it did stay.
`resume`	Continues waiting work whose decisions are all made.
`restart`	Restarts stopped work on the current code, reusing earlier saved stages. Needs `--reason`. `--stage` reruns that stage and everything after it.
`config`	The effective `work-items.yaml`.

See the SDK guide work items (opens in a new tab).

hubzoid operations

Recorded external writes of work items: sends, comments and documents, each recorded before anything is sent.

Usage

hubzoid operations list [HUB] [--state STATE] [--json]
hubzoid operations show [HUB] OP_ID [--json]
hubzoid operations approve [HUB] OP_ID --digest sha256:... [--expected-revision N] [--json]
hubzoid operations deny [HUB] OP_ID [--reason TEXT] [--expected-revision N] [--json]
hubzoid operations resolve [HUB] OP_ID --decision done|retry|abandon [--evidence TEXT] [--acknowledge-duplicate-risk] [--expected-revision N] [--json]

Subcommand	What it does
`list`	Recorded external writes, newest first. `--state ambiguous` lists what needs a decision.
`show`	One operation, with the exact content a person approves.
`approve`	Approves the exact content you reviewed (`--digest`). The work continues and sends it once.
`deny`	Denies a waiting operation. The work stops and nothing is sent.
`resolve`	Decides an operation whose outcome is unknown: `done`, `retry` or `abandon`.

hubzoid stations

Isolated agents (stations) that work-item workflows call for one stage each.

Usage

hubzoid stations validate [HUB] [--json]
hubzoid stations doctor [HUB] [--json]
hubzoid stations calls list|show|retry ...

Subcommand	What it does
`validate`	Checks every isolated agent: engine, tools, schema and sandbox. Nothing runs.
`doctor`	Each station's digest, engine, model, exact tools and schema, and whether its engine's login is available. Never prints a credential.
`calls list`	Station calls of one work item.
`calls show`	One station call: attempts, pinned definition digest, output or error.
`calls retry`	Directs a failed call's one retry after its workflow stopped without using it. The work continues from that call.

See the SDK guide stations (opens in a new tab).

hubzoid handoffs

Handoff documents that stations of one work item pass to each other.

Usage

hubzoid handoffs list [HUB] --work-item ID [--json]
hubzoid handoffs read [HUB] --work-item ID --id HANDOFF_ID [--json]

Subcommand	What it does
`list`	Handoff documents of one work item.
`read`	One handoff document, as text.

hubzoid requests

Approvals and questions waiting for a person.

Usage

hubzoid requests list [HUB] [--all] [--user EMAIL] [--json]
hubzoid requests show HUB REQUEST_ID [--user EMAIL] [--json]
hubzoid requests decide HUB REQUEST_ID --decision DECISION [--answer TEXT] [--note TEXT] [--user EMAIL] [--json]
hubzoid requests cancel HUB REQUEST_ID [--user EMAIL] [--json]

Subcommand	What it does
`list`	Open requests. `--all` includes decided ones.
`show`	One request. The first 8 characters of its id are enough.
`decide`	`--decision` is `approve`, `approve_chat`, `approve_always`, `reject`, `request_changes` or `answer`.
`cancel`	Cancels a request.

hubzoid hitl

When the agent asks a person first, from hitl.yaml.

Usage

hubzoid hitl validate [HUB] [--file PATH] [--json]
hubzoid hitl export [HUB] [--json]
hubzoid hitl apply [HUB] --file PATH --expected-revision REV [--json]

validate checks a file (default: the Hub's hitl.yaml). export prints the active rules and their revision. apply writes a file: pass the revision you exported, or absent to create it. See Hub files.

hubzoid workflow-access

Who may run, schedule, edit, approve and see each workflow, from workflows/access.yaml.

Usage

hubzoid workflow-access resources [HUB] [--user EMAIL] [--json]
hubzoid workflow-access export [HUB] [--output PATH] [--json]
hubzoid workflow-access validate|diff [HUB] [--file PATH] [--json]
hubzoid workflow-access apply [HUB] [--file PATH] --expected-revision N [--user EMAIL] [--json]
hubzoid workflow-access explain [HUB] --workflow NAME --action ACTION [--subject EMAIL] [--user EMAIL] [--json]

Subcommand	What it does
`resources`	The workflows and the actions you can grant on them.
`export`	The active rules as a file.
`validate`	Checks a file (default `workflows/access.yaml`).
`diff`	What applying the file would change.
`apply`	Applies the file at the revision you read.
`explain`	Whether a person may take one action on one workflow, and why.

Accounts and access

hubzoid admin

Accounts for the web app, for the server's operator. These commands work without signing in, on the deployment's shared account store. Passwords are typed at a hidden prompt, never passed as arguments and never printed.

Usage

hubzoid admin create EMAIL [HUB] [--name NAME] [--admin] [--owner] [--password | --link] [--google-only]
hubzoid admin reset-password EMAIL [HUB] [--password]
hubzoid admin list [HUB] [--json]
hubzoid admin set-role EMAIL ROLE [HUB]
hubzoid admin capabilities|overview [HUB] [--json]
hubzoid admin config|domain|diagnostics SUBCOMMAND ...

Subcommand	What it does
`create`	Creates an account and, by default, prints a one-time sign-in link where they set their password. Refuses an email that already has an account, a blocked email and a localhost address.
`reset-password`	Ends their sessions, stops the current password working and prints a one-time link to set a new one. With `--password` you type the new password instead. Refuses an account that signs in with Google only.
`list`	Every account with email, name, role, status, how they sign in and last sign-in.
`set-role`	`admin` makes someone an Administrator and `user` a User. Sets Hubzoid administration and the web app's admin role together, signs them out so the change applies at once, and approves an account awaiting approval. Refuses to demote the last administrator.
`capabilities`	What this operator may do, the settings domains and the diagnostic checks.
`overview`	Deployment cards for the last `--days` days (default `7`). Unknown values are null, never zero.
`config`	`admin.yaml` diagnostic limits: `show`, `validate`, `export`.
`domain show`	One settings domain of the settings registry, or all of them.
`diagnostics`	Read-only diagnostic reports and support bundles: `checks`, `run`, `list`, `show`, `cancel`, `bundle`, `bundle-delete`. Bundles hold metadata only and are never deleted automatically.

Option	Applies to	What it does
`HUB`	all	Any Hub of the deployment. Default `.`.
`--name`	`create`	Their name. Default: the part of the email before `@`.
`--admin`	`create`	Make them an Administrator.
`--owner`	`create`	Give them the owner's access on every Hub of the deployment. Implies `--admin`.
`--password` / `--link`	`create`	Type their password now, or print a one-time sign-in link (the default). `reset-password` takes `--password` only.
`--google-only`	`create`	They sign in with Google only, with no password and no link. Google sign-in attaches to the account only with `OAUTH_MERGE_ACCOUNTS_BY_EMAIL=true`.

One-time links work once and expire after 72 hours (HUBZOID_LINK_HOURS). They are built from HUBZOID_PUBLIC_URL, else http://127.0.0.1:<PORT>, and nothing is emailed: share the link yourself. Passwords are 8 to 1024 characters. Exit codes: 1 when the change is refused (an existing or unknown account, the last administrator), 2 for an invalid email, password or role, or a folder that is not a Hub. See access administration.

hubzoid auth

Your own account on a hosted Hubzoid, from any computer. The session is saved for that server, never the password.

Usage

hubzoid auth login [--server URL] [--email EMAIL] [--password-stdin]
hubzoid auth logout [--server URL]
hubzoid auth whoami [--server URL] [--json]
hubzoid auth bootstrap [HUB] --email EMAIL [--name NAME] [--password-stdin]
hubzoid auth keys list|create|revoke
hubzoid auth sessions list|revoke|revoke-others
hubzoid auth mfa status|policy

Subcommand	What it does
`login`	Signs in with your password, and a code when you use two-step sign-in.
`logout`	Signs this computer out, on the server too.
`whoami`	Who the saved session or `HUBZOID_API_KEY` signs in as.
`bootstrap`	Moves a laptop Hub to team sign-in: the local owner becomes a password account with the same id, so conversations and grants stay theirs. Run it on the server's own machine, then set `HUBZOID_AUTH=true` and restart.
`keys`	Personal API keys (`hzp_...`). `create` prints the key once.
`sessions`	Your signed-in devices.
`mfa`	Your two-step sign-in `status`, and the `policy` of who must use it: `none`, `admins` or `all`. Administrators change the policy.

--server defaults to HUBZOID_SERVER. See authentication.

hubzoid grant

grant, revoke and access act on the access store of the Hub, or the shared store of its deployment. grant and revoke print the store they write to, with any password hidden.

Usage

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

Argument or option	Default	What it does
`SUBJECT`	required	An account email. The account need not exist yet. A legacy `workflow:<name>` subject is still accepted, but runs that act as an account do not use its grants.
`PERMISSION`	required	For example `use_hub`, `manage_access` or the file stem of a restricted tool.
`HUB_DIR`	`.`	Hub folder, used to find the access store.
`--hub`	the Hub folder name	Hub the grant applies to.
`--org`	off	Grant across every Hub. Only for `manage_access`.

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 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 what a workflow needs to the account it runs as.

hubzoid revoke

Usage

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. Refuses to remove the last organization admin, with code 1.

hubzoid access

Usage

hubzoid access check SUBJECT [HUB_DIR] [--hub NAME] [--json]
hubzoid access list [HUB_DIR] [--hub NAME] [--json]
hubzoid access bootstrap [HUB_DIR] [--admin SUBJECT ...]

Subcommand	What it does
`check`	Every permission a subject effectively holds in a Hub, including organization and public grants. `--hub` defaults to the Hub folder name.
`list`	All grants as subject, permission and Hub. `--hub` limits the list to one Hub.
`bootstrap`	Break-glass for a deployment nobody can administer. Grants organization `manage_access` to each `--admin` (repeatable). It acts once per access store, so use Settings or `hubzoid admin set-role` after that.

hubzoid audit

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

Usage

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

Option	Default	What it does
`--limit`, `-n`	`50`	Show the most recent N decisions.
`--user`		Only this person.
`--denied`	off	Only denied attempts.
`--json`	off	Print only JSON: `{entries: [{ts, user, decision, tool, surface, reason}]}`.

The decisions come from the operational database, where the runtime records every restricted tool call. Each line shows the time, person, ALLOW or DENY, the tool, and the surface with the reason. Settings → Activity → Audit log shows the same decisions under Tool decisions. See people and activity.

Channels and embedding

hubzoid channels

Channel connections of a Hub: Slack, GitHub, Linear, email and WhatsApp threads. Each connection is a file in channels/ named by its id.

Usage

hubzoid channels list [HUB] [--json]
hubzoid channels validate [HUB] --file PATH [--json]
hubzoid channels apply [HUB] --file PATH --expected-revision REV [--json]
hubzoid channels export|doctor|pause|resume|threads|inspect|deliveries|outbox|subscribe|unsubscribe|links|link [HUB] ID [options]
hubzoid channels redrive [HUB] ID DELIVERY
hubzoid channels reconcile [HUB] ID OPERATION [--decision check|done|retry|abandon]
hubzoid channels unlink [HUB] ID LINK
hubzoid channels slack|github|linear|email SUBCOMMAND ...

Subcommand	What it does
`list`	Connections with status, revision and backlog.
`validate`	Checks a channel file without activating it. No network writes.
`apply`	Validates the file, saves it as `channels/<id>.yaml` and makes it active.
`export`	The active configuration, with secret references and never values. `--format yaml` or `json`.
`doctor`	Read-only checks. Never posts or subscribes. `--actor` checks one provider user end to end.
`pause`, `resume`	Stop or restart new intake. Accepted work and its replies continue. Run `doctor` before `resume`.
`threads`, `inspect`	Threads this connection has seen, and one thread (`--thread`) with its origin, deliveries, replies and work.
`deliveries`, `redrive`	Verified deliveries and what happened to each, and routing a failed, denied or paused one again under its original identity and today's permissions.
`outbox`, `reconcile`	Replies recorded for this connection, and settling an uncertain one. `check` only looks. Nothing is resent unless you choose `retry` and accept the duplicate risk.
`subscribe`, `unsubscribe`	Whether follow-ups in a thread continue the work without a new mention.
`link`, `unlink`, `links`	Let a provider account (`--external-id`) act as a Hubzoid account (`--account`) in this Hub.
`slack`	`manifest`, and `import-legacy` to write a disabled channel file for an existing `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN` setup.
`github`	`connect`, `import-app`, `repositories`, `configure`, `intake`, `call`, `setup`: your own GitHub App or a local token.
`linear`	`setup`, `connect`, `disconnect`, `sessions`: the Hub's agent app in Linear.
`email`	`status`, `connect`, `poll`, `import-history`, `rehearse-draft`: a shared Gmail or Microsoft 365 mailbox. Nothing is sent by these.

See Slack and WhatsApp and Telegram.

hubzoid intake

Review email and WhatsApp messages from outside your organization before any work starts.

Usage

hubzoid intake list [HUB] [--state STATE] [--channel ID] [--json]
hubzoid intake show [HUB] ITEM [--json]
hubzoid intake release [HUB] ITEM --reason TEXT --expected-revision N [--json]
hubzoid intake reject [HUB] ITEM [--reason TEXT] --expected-revision N [--json]
hubzoid intake retry [HUB] ITEM --expected-revision N [--json]

Subcommand	What it does
`list`	Intake items, oldest first.
`show`	One item with its text and attachments, shown as untrusted data.
`release`	Starts work on a quarantined item. This approves nothing it later wants to send.
`reject`	Closes an item without starting work. Nothing is sent to the sender.
`retry`	Fetches a failed item's attachments again.

hubzoid slack

Run the Slack adapter on its own, or print its manifest and service unit. The adapter uses Socket Mode, so it needs no public URL.

Usage

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

Subcommand	What it does
`run`	Starts the adapter in the foreground. The Hub's bridge must already be running. Reads `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN` from the Hub's `.env`, and exits with code `2` when either is missing or the Hub has no `AGENTS.md`.
`manifest`	Prints a Slack app manifest filled in from `AGENTS.md`. `--format` defaults to `json`.
`systemd`	Prints a unit for `hubzoid-slack@<hub>.service`. `--user` defaults to `hubzoid`, `--python` to the interpreter running the command.

hubzoid run starts the same adapter with its Hub when the Hub's channels/ folder has a file for it, so do not also run it on its own. See Slack.

hubzoid inbound

The receiver for WhatsApp, Telegram and the generic webhook.

Usage

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

Subcommand	What it does
`run`	Serves every configured surface on `127.0.0.1:HUBZOID_INBOUND_PORT` (default `8100`) under `/webhooks/<hub>/`. The bridge must already be running. Exits with code `1` when no surface is configured and `2` when the Hub has no `AGENTS.md`.
`systemd`	Prints a unit for `hubzoid-inbound@<hub>.service`. Same options as `slack systemd`.

hubzoid run starts the same receiver with its Hub when a channel file turns on WhatsApp, Telegram or the generic webhook. Named webhooks for code workflows are served by the bridge and need no receiver. See WhatsApp and Telegram and webhooks.

hubzoid embed

Apps that embed the chat, registered under apps: in hubzoid.yaml.

Usage

hubzoid embed secret APP_ID [--hub PATH] [--origin URL ...] [--agent NAME ...] [--tool NAME ...] [--token-to TOOL ...] [--rotate]
hubzoid embed list [--hub PATH] [--json]
hubzoid embed pass APP_ID USER [--hub PATH] [--minutes N] [--tool NAME ...] [--app-token TOKEN]

Subcommand	What it does
`secret`	Makes the app's client secret, stores it write-only and shows it once, with the `hubzoid.yaml` entry to paste and the settings for the app's server. `--origin`, `--agent`, `--tool` and `--token-to` fill that entry (repeatable). `--rotate` replaces an existing secret.
`list`	The registered apps and whether each one is ready.
`pass`	A short pass for a pass-mode app, signed with its secret, to try the chat by hand. `--minutes` is 1 to 60, default `10`.

See configuration and the /api/agui endpoint.

Hub content and limits

hubzoid hub-changes

Proposed changes to a Hub's own instructions and knowledge. These commands work from the CLI whether or not in_app_editing is on.

Usage

hubzoid hub-changes list HUB [--status STATUS] [--json]
hubzoid hub-changes show HUB CHANGE_ID [--json]
hubzoid hub-changes propose HUB --title TEXT --edits FILE [--reason TEXT] [--user EMAIL] [--json]
hubzoid hub-changes decide HUB CHANGE_ID --decision approve|reject [--note TEXT] [--user EMAIL] [--json]
hubzoid hub-changes undo HUB CHANGE_ID [--user EMAIL] [--json]

Subcommand	What it does
`list`	Proposed changes, filtered by `--status`.
`show`	One change by number.
`propose`	Proposes a change. `--edits` is a JSON file with a list of edits.
`decide`	Approves or rejects a change.
`undo`	Undoes an applied change.

hubzoid workspace

Draft, review and publish agent, skill and prompt files.

Usage

hubzoid workspace files [HUB] [--json]
hubzoid workspace versions PATH [--hub PATH] [--json]
hubzoid workspace openapi-preview [HUB] --file SPEC [--select OPERATION_ID] [--json]
hubzoid workspace drafts create|update|show|submit|review|publish|rollback ...
hubzoid workspace prompts list|render ...

Subcommand	What it does
`files`	The Hub's editable files.
`versions`	The versions of one file.
`openapi-preview`	The tools an OpenAPI document (JSON or YAML) would become. `--select` picks operation ids.
`drafts`	Drafts of Hub files, from create to publish or rollback.
`prompts`	Shared and personal prompts.

hubzoid knowledge

Sources: collections, sync, query, citations and safe fetch.

Usage

hubzoid knowledge sync COLLECTION [--hub PATH] [--json]
hubzoid knowledge query TEXT [--hub PATH] [--collection NAME] [--top-k N] [--json]
hubzoid knowledge citation CITATION [--hub PATH] [--json]
hubzoid knowledge fetch URL [--hub PATH] [--json]
hubzoid knowledge collections list|get|apply|export|delete ...
hubzoid knowledge jobs get|wait ...

Subcommand	What it does
`sync`	Extracts, indexes and publishes a collection's sources, and waits for the result.
`query`	Searches the sources.
`citation`	Resolves one citation.
`fetch`	Fetches one public `https` page with the safe loader and shows its text.
`collections`	Collections of sources. `export` prints a collection's manifest as YAML.
`jobs`	Syncs and their outcome.

hubzoid models

Usage

hubzoid models catalog [HUB] [--user EMAIL] [--json]
hubzoid models presets list|put|delete ...

catalog lists the models people may pick in chat, from chat.models.catalog in hubzoid.yaml. Without a catalog, people see only the agent's own model. presets manages your presets and the Hub's shared ones.

hubzoid secrets

Secrets stored in Hubzoid's database. Values are never shown.

Usage

hubzoid secrets list [HUB] [--skip-secret-fetch] [--json]
hubzoid secrets set [HUB] (--name NAME | --ref REF) [--restricted | --not-restricted] [--deployment] [--stdin] [--expected-revision REV] [--check] [--json]
hubzoid secrets delete [HUB] (--name NAME | --ref REF) [--deployment] [--expected-revision REV] [--check] [--json]

Subcommand	What it does
`list`	Every secret the Hub uses or expects: level, status and source, never a value.
`set`	Stores a secret. The value is asked for hidden, or read with `--stdin`. `--restricted` makes it visible to restricted tools only. `--deployment` shares it with every Hub of the deployment. `--check` writes nothing.
`delete`	Removes a stored secret. Operator sources (`.env`, AWS) are never touched.

Keys a person types, such as model keys, belong in .env. The store refuses them and names the .env to use. See configuration secrets.

hubzoid budgets

Usage limits from budgets.yaml: tokens, turns or dollars per run, per work item and per month.

Usage

hubzoid budgets show [HUB] [--json]
hubzoid budgets validate [HUB] [--file PATH] [--json]
hubzoid budgets apply [HUB] --file PATH --expected-revision REV [--json]
hubzoid budgets release [HUB] RESERVATION --reason TEXT [--json]

Subcommand	What it does
`show`	The limits in force, this month's usage and reservations still open.
`validate`	Checks `budgets.yaml`, or `--file`. Nothing changes.
`apply`	Replaces `budgets.yaml` after validating it. Running work keeps what it spent, and the next model call is checked against the new limits.
`release`	Releases a reservation whose call never reported, after you check the provider's own usage. Recorded in the audit log.

See the SDK guide usage limits (opens in a new tab).

hubzoid sandbox

Sandboxes where an agent runs commands, tests and git in an isolated Docker container.

Usage

hubzoid sandbox doctor|config [HUB] [--json]
hubzoid sandbox try [HUB] --profile ID -- COMMAND
hubzoid sandbox list [HUB] [--state STATE] [--owner-kind KIND] [--limit N] [--json]
hubzoid sandbox show [HUB] SANDBOX_ID [--json]
hubzoid sandbox stop|delete [HUB] SANDBOX_ID --reason TEXT [--expected-revision N] [--json]
hubzoid sandbox reap [HUB] [--execute] [--json]
hubzoid sandbox profiles list|validate|prepare ...

Subcommand	What it does
`doctor`	Whether Docker is reachable and every profile is valid and prepared. Creates nothing.
`config`	The effective `sandbox.yaml`.
`try`	Runs one command in a fresh sandbox of a profile, after its setup, offline. The sandbox is deleted afterwards.
`list`, `show`	Sandboxes of this Hub, newest first, and one sandbox's owner, profile, state, network policy and setup result. No file contents.
`stop`	Stops a sandbox's processes. Its files are kept and its owner resumes it.
`delete`	Deletes a sandbox. Hub files and outputs stay.
`reap`	Stops idle sandboxes and removes finished or expired ones and leftover containers. Without `--execute` it only shows what would happen.
`profiles`	Profiles in `sandboxes/<id>.yaml`. `prepare` builds or pulls a profile's image ahead of use.

See the SDK guide sandboxes (opens in a new tab).

hubzoid apps

Cards: tool results shown as MCP Apps in chat, configured in mcp-apps.yaml and cards/*.yaml.

Usage

hubzoid apps validate [HUB] [--check] [--json]
hubzoid apps apply [HUB] --expected-revision REV [--json]
hubzoid apps list [HUB] [--as EMAIL] [--json]
hubzoid apps invoke [HUB] CARD_ID --idempotency-key KEY [--args-file PATH] [--as EMAIL] [--json]
hubzoid apps inspect [HUB] INSTANCE_ID [--format text|json]
hubzoid apps dispatch [HUB] --instance ID --method METHOD [--params-file PATH] [--as EMAIL] [--json]
hubzoid apps revoke [HUB] INSTANCE_ID [--reason TEXT] [--json]
hubzoid apps probe [HUB] [--client-capabilities none|mcp-apps|FILE] [--json]
hubzoid apps config get|set ...

Subcommand	What it does
`validate`	Checks `mcp-apps.yaml` and `cards/*.yaml` against the Hub's tools. `--check` exits with code `2` when there are errors.
`apply`	Makes the checked files the next active revision.
`list`	Recent cards made for a person, default the Hub's owner.
`invoke`	Runs a card's tool for real, under that person's grants, and shows the card.
`inspect`	A card's result, text, state and binding, without a browser.
`dispatch`	Sends one card request as the card frame would. It has no decision authority.
`revoke`	Stops a card from making any further request.
`probe`	How a client with given capabilities would get each card, rendered or as text. A protocol check, not a claim that a host works.
`config`	The active card configuration. `set` changes one value by JSON Pointer.

hubzoid apps is about cards. Embedding the chat in your own app is hubzoid embed.

hubzoid branding

Usage

hubzoid branding inspect [HUB] [--json]
hubzoid branding validate [HUB] [--json]
hubzoid branding import-legacy [HUB] [--write] [--json]

inspect shows where the brand is authored, what is active and any legacy files. validate checks the brand as every agent reads it: the brand section (or branding.yaml), branding/theme.json and every file it names. import-legacy maps an older branding/ folder to branding.yaml, and --write writes it without overwriting one.

Chat records

hubzoid chat

Chat settings, theme, personal preferences and conversation records, from the command line. Each subgroup has its own --help.

Subgroup	What it covers
`capabilities`	Which chat features this install provides.
`config`	The deployment's chat configuration: `schema`, `get` (`--sources` adds where each value comes from), `validate`.
`theme`, `preferences`	Theme tokens shared by chat and Settings (`validate`, `inspect`), and one person's appearance preferences (`get`, `set`).
`conversations`, `organize`, `title`	Create, read, keep and delete conversations, and their folder, pin, archive, tags and title.
`operations`, `runs`, `queue`, `branches`, `view`	Send and revise messages, follow replies being written, queued follow-ups and branches. A reply is written before `operations submit` returns.
`deletion`, `feedback`, `helpers`	Preview what a deletion removes, ratings of answers, and generated follow-ups and titles.
`notifications`, `shares`, `collaborators`	Your inbox and notification targets, snapshot links and who can read or write a conversation.
`folders`, `tags`, `bookmarks`, `search`	Personal folders, tags and bookmarks, and full-text search.
`organization`, `exports`, `imports`	Organization export, manifests and bulk changes, and moving conversations as a `hubzoid-exchange` package.
`shortcuts`, `devices`	Keyboard shortcuts, and install metadata and the tested device list.

hubzoid files

Chat files: upload, reuse, download and delete.

Usage

hubzoid files upload PATH [--hub PATH] [--conversation ID] [--no-wait] [--json]
hubzoid files list [HUB] [--conversation ID] [--json]
hubzoid files download FILE_ID --output PATH [--hub PATH]
hubzoid files wait|status|preview|attach|references|detach|delete FILE_ID [options]
hubzoid files doctor [HUB] [--json]

doctor writes, reads and deletes a synthetic object with the configured storage. The others take --user EMAIL and act as that person.

hubzoid artifacts

Documents made in conversations and their versions.

Usage

hubzoid artifacts list [HUB] --conversation ID [--json]
hubzoid artifacts show ARTIFACT_ID [--hub PATH] [--json]
hubzoid artifacts download ARTIFACT_ID --output PATH [--version V] [--hub PATH]
hubzoid artifacts revise ARTIFACT_ID --file PATH --base-version V --expected-revision N [--hub PATH]

Operations

hubzoid backup

Save a deployment's databases, accounts, conversations and Hub state to one verified archive while chat keeps working. hubzoid backup [HUB] runs create.

Usage

hubzoid backup [create] [HUB] [--out PATH] [--include-secrets] [--wait SECONDS]
hubzoid backup verify ARCHIVE [--json]
hubzoid backup list [HUB] [--json]

Argument or option	Default	What it does
`HUB`	`.`	A Hub folder. A Hub that runs with others backs up the whole deployment.
`--out`, `-o`	`./hubzoid-backup-<time>.tar.gz`	Archive path.
`--include-secrets`	off	Also save `.env` files, the deployment key, signing keys and database passwords.
`--wait`	`600`	Seconds to wait for running scheduled work to finish. `0` does not wait.

Subcommand	What it does
`create`	New scheduled runs are held and running ones finish first. PostgreSQL databases are saved with `pg_dump`. The archive is verified before it counts.
`verify`	Checks an archive: every file's checksum, each database's integrity and each PostgreSQL dump. Exits with code `1` when it fails.
`list`	The scheduled backups kept for this deployment, newest first.

Scheduled backups run weekly by default (HUBZOID_BACKUPS=weekly, daily or off). Hub content (AGENTS.md, skills, knowledge) belongs in Git and is not included. The archive holds accounts and chats, so store it like a secret. Without --include-secrets, keep protected copies of the .env files and the deployment key separately. create exits with code 1 on error. See backup and restore.

hubzoid restore

Put a backup back. Stop hubzoid run first.

Usage

hubzoid restore ARCHIVE [--move OLD=NEW ...] [--dry-run] [--rehearse] [--postgres] [--postgres-env NAME] [--json]

Argument or option	Default	What it does
`ARCHIVE`	required	An archive written by `hubzoid backup`.
`--move`		`OLD=NEW`. Restore paths under `OLD` to `NEW` instead. Repeatable.
`--dry-run`	off	Print where everything would go and stop.
`--rehearse`	off	Restore into a scratch folder, upgrade the copies, report and clean up. Touches nothing else.
`--postgres`	off	Also load the archive's PostgreSQL dump into the database named by `--postgres-env`.
`--postgres-env`	`DATABASE_URL`	The environment variable holding that database's URL. With `--rehearse`, a server where a temporary database is created and dropped. A database URL is never given on the command line.
`--json`	off	With `--rehearse`, print the report as JSON.

Everything returns to its original path unless moved. Whatever is at a target now is kept beside it as <name>.pre-restore-<time>. Secret files the archive does not hold stay as they are, so restoring in place keeps the current deployment key. Run hubzoid doctor after starting. Exit codes: 2 for a malformed --move or an unset --postgres-env variable, 1 on any other error or a failed rehearsal.

hubzoid deploy

Host a Hub on a provider.

Usage

hubzoid deploy init PROVIDER [HUB] [--image IMAGE] [--force] [--json]
hubzoid deploy verify URL [--allow-http] [--json]

Subcommand	What it does
`init`	Writes the `Dockerfile`, `.dockerignore` and `deploy/<provider>/` (steps and variables) for `railway` or `maritime`. `--image` defaults to this release's image. Never replaces a file without `--force`.
`verify`	Checks a hosted Hub from outside: HTTPS, the health check, that app data needs sign-in, and that `HUBZOID_PUBLIC_URL` is this address. `--allow-http` warns instead of failing for plain HTTP. Exits with code `1` when a check fails.

See Docker.

hubzoid migrate

Move an Open WebUI install to the Hubzoid web app.

Usage

hubzoid migrate openwebui [PATH] [--owui-db URL] [--apply] [--rehearse DIR] [--model-alias OLD=AGENT ...] [--verbose] [--json]
hubzoid migrate readiness [PATH] [--owui-db URL] [--output FILE] [--json]

Subcommand	What it does
`openwebui`	Moves accounts, conversations and share links. Open WebUI is read, never changed. The default is a dry run. Stop the deployment and take a backup before `--apply`. `--rehearse` migrates a copy in an empty folder.
`readiness`	What moving off Open WebUI would take. Reads only. `--output` also writes the report as Markdown.

PATH is a Hub folder, a Hub of a deployment, or a gateway data folder. See upgrading.

hubzoid api

Call any Hubzoid API route as yourself and print the answer.

Usage

hubzoid api METHOD PATH [--data JSON|@FILE] [--server URL]

METHOD is GET, POST, PUT, PATCH or DELETE. PATH is the route, for example /api/agents. It signs in with the session saved by hubzoid auth login, or HUBZOID_API_KEY. --server defaults to HUBZOID_SERVER. See HTTP endpoints.

hubzoid version

Usage

hubzoid version

Prints the installed Hubzoid version. hubzoid --version does the same. Run it before and after an upgrade.

CLI reference

ConventionsCopy Anchor Link

Command indexCopy Anchor Link

Create and runCopy Anchor Link

hubzoid initCopy Anchor Link

hubzoid new workflowCopy Anchor Link

hubzoid runCopy Anchor Link

Control a running deploymentCopy Anchor Link

hubzoid upgradeCopy Anchor Link

hubzoid service installCopy Anchor Link

hubzoid gatewayCopy Anchor Link

Test and checkCopy Anchor Link

hubzoid testCopy Anchor Link

hubzoid doctorCopy Anchor Link

hubzoid evalCopy Anchor Link

hubzoid hubCopy Anchor Link

Schedules and workCopy Anchor Link

hubzoid scheduleCopy Anchor Link

hubzoid work-itemsCopy Anchor Link

hubzoid operationsCopy Anchor Link

hubzoid stationsCopy Anchor Link

hubzoid handoffsCopy Anchor Link

hubzoid requestsCopy Anchor Link

hubzoid hitlCopy Anchor Link

hubzoid workflow-accessCopy Anchor Link

Accounts and accessCopy Anchor Link

hubzoid adminCopy Anchor Link

hubzoid authCopy Anchor Link

hubzoid grantCopy Anchor Link

hubzoid revokeCopy Anchor Link

hubzoid accessCopy Anchor Link

hubzoid auditCopy Anchor Link

Channels and embeddingCopy Anchor Link

hubzoid channelsCopy Anchor Link

hubzoid intakeCopy Anchor Link

hubzoid slackCopy Anchor Link

hubzoid inboundCopy Anchor Link

hubzoid embedCopy Anchor Link

Hub content and limitsCopy Anchor Link

hubzoid hub-changesCopy Anchor Link

hubzoid workspaceCopy Anchor Link

hubzoid knowledgeCopy Anchor Link

hubzoid modelsCopy Anchor Link

hubzoid secretsCopy Anchor Link

hubzoid budgetsCopy Anchor Link

hubzoid sandboxCopy Anchor Link

hubzoid appsCopy Anchor Link

hubzoid brandingCopy Anchor Link

Chat recordsCopy Anchor Link

hubzoid chatCopy Anchor Link

hubzoid filesCopy Anchor Link

hubzoid artifactsCopy Anchor Link

OperationsCopy Anchor Link

hubzoid backupCopy Anchor Link

hubzoid restoreCopy Anchor Link

hubzoid deployCopy Anchor Link

hubzoid migrateCopy Anchor Link

hubzoid apiCopy Anchor Link

hubzoid versionCopy Anchor Link

Next stepsCopy Anchor Link

Configuration

Doctor checks

Operating runs

Hub files

On this page

Conventions

Command index

Create and run

hubzoid init

hubzoid new workflow

hubzoid run

Control a running deployment

hubzoid upgrade

hubzoid service install

hubzoid gateway

Test and check

hubzoid test

hubzoid doctor

hubzoid eval

hubzoid hub

Schedules and work

hubzoid schedule

hubzoid work-items

hubzoid operations

hubzoid stations

hubzoid handoffs

hubzoid requests

hubzoid hitl

hubzoid workflow-access

Accounts and access

hubzoid admin

hubzoid auth

hubzoid grant

hubzoid revoke

hubzoid access

hubzoid audit

Channels and embedding

hubzoid channels

hubzoid intake

hubzoid slack

hubzoid inbound

hubzoid embed

Hub content and limits

hubzoid hub-changes

hubzoid workspace

hubzoid knowledge

hubzoid models

hubzoid secrets

hubzoid budgets

hubzoid sandbox

hubzoid apps

hubzoid branding

Chat records

hubzoid chat

hubzoid files

hubzoid artifacts

Operations

hubzoid backup

hubzoid restore

hubzoid deploy

hubzoid migrate

hubzoid api

hubzoid version

Next steps