hal0 CLI reference

The hal0 CLI is built with Typer. The entry point is hal0 = "hal0.cli.main:app". Most subcommands are thin HTTP clients over the hal0-api daemon; a few (config show/edit/migrate/validate, registry import, agent install, memory migrate, capabilities migrate, the slot migrate-* family) read or write on-disk state directly and work without a running daemon.

hal0 --help          # top-level help (no args also prints help)
hal0 <group> --help  # per-group help, e.g. hal0 slot --help

Global

Flag	Behavior
`--version` / `-V`	Print `hal0 {version}` and exit (eager callback).
`--help`	Print help. No flag = help (root app has `no_args_is_help=True`).
`--install-completion` / `--show-completion`	Typer’s built-in shell-completion helpers (`add_completion=True`).

There is no global --verbose or --config flag. Behavior that would normally be a global flag is controlled per-command via environment variables instead — see Environment variables (HAL0_API_URL, HAL0_HOME, HAL0_BIND_HOST, HAL0_PORT, HAL0_FORCE, HAL0_PLAIN, etc).

Top-level commands

Command	Purpose	Flags
`hal0 status`	System + slot summary.	—
`hal0 probe`	Deprecated, hidden. Alias for `hal0 config hardware --refresh`.	—
`hal0 serve`	Start the hal0 API server (used by `hal0-api.service`).	`--host` (default `127.0.0.1`, env `HAL0_BIND_HOST`), `--port` (default `8080`, env `HAL0_PORT`), `--reload`
`hal0 uninstall`	Uninstall hal0. Conservative by default.	`--purge` (alias `--clean-slate`), `--keep-data`, `--force`/`-f` (honors `HAL0_FORCE=1`), `--dev` (tears down a dev install at `$PWD/.hal0ai`)
`hal0 bench ...`	Benchmark pipeline. Raw argparse passthrough (`allow_extra_args`), see Model roster & benchmarks.	verbs: `plan, run, worker, status, results, history, reindex, devices, publish, eval, bundle, upload`
`hal0 chat`	Interactive chat REPL.	`--model` (default `"agent"`), `--base-url` (default `http://127.0.0.1:8080/v1`, env `HAL0_CHAT_BASE_URL`), `--no-stream`, `--brain` (talk to the hal0-brain steward instead)
`hal0 system-info`	Host system info.	`--json`
`hal0 ports`	Port allocation view.	`--json`
`hal0 setup`	First-run provisioning (internal fallback in v1.0 — see caution above).	see below
`hal0 update ...`	Check/apply/roll back an update.	see below

hal0 chat in-REPL slash commands: /think on|off|default, /clear, /quit / /exit (Ctrl-D also exits).

`hal0 setup`

hal0 setup [--auto] [--storage-dir DIR] [--no-pull] [--no-extensions] [--no-slots]
           [--answers FILE] [--emit-answers FILE] [--plan]

Flag	Default	Meaning
`--auto`	`False`	Non-interactive, applies recommended defaults.
`--storage-dir`	`/var/lib/hal0/models`	Model storage root.
`--no-pull`	`False`	Skip pulling a starter model.
`--no-extensions`	`False`	Skip optional-extension prompts.
`--no-slots`	`False`	Skip seeding starter slots.
`--answers`	unset	Path to a `hal0-setup.yaml` answers file.
`--emit-answers`	unset	Write resolved answers to a file and exit, without applying.
`--plan` (alias `--dry-run`)	`False`	Resolve and print the plan; write nothing.

`hal0 update`

hal0 update [--channel stable|preview|nightly] [--check] [--rollback]
            [--target VERSION] [--yes|-y] [--restart-slots]

Flag	Meaning
`--channel`	Persist the update channel, then check it.
`--check`	Check only; don’t apply.
`--rollback`	Roll back to the previous version.
`--target`	Pin an exact version.
`--yes` / `-y`	Skip the confirmation prompt.
`--restart-slots`	Bounce only drifted slots after update.

hal0 update owui manages the bundled OpenWebUI container separately: --check, --tag (upstream tag, default :main; ignored if --target set), --target (pin an explicit digest), --yes/-y, --force (repin/pull/restart even if the digest already matches).

`hal0 slot` — manage inference slots

Command	Args	Flags
`slot list`	—	`--json`
`slot status <name>`	`name`	`--json`
`slot load <name>`	`name`	`--model`/`-m`
`slot unload <name>`	`name`	—
`slot restart <name>`	`name`	—
`slot rename <name> <new_name>`	`name`, `new_name`	—
`slot swap <name>`	`name`	`--model`/`-m` (required), `--no-persist`
`slot logs <name>`	`name`	`--follow`/`-f`, `--lines`/`-n` (default 200, 1-5000)
`slot create <name>`	`name`	`--type`/`-t` (default `llm`), `--provider` (default `llama-server`), `--hardware` (default: auto-detect), `--backend`/`-b` (hidden, deprecated alias for `--provider`), `--model`/`-m` (required), `--port`/`-p` (default: auto-assign, 1024-65535), `--ctx-size` (default `4096`, min `128`)
`slot edit <name>`	`name`	`--model`/`-m`, `--port`/`-p`, `--ctx-size`, `--provider`, `--hardware`, `--backend`/`-b` (hidden, deprecated)
`slot delete <name>`	`name`	`--force`/`-f`
`slot add <name>`	`name`	hidden, deprecated alias for `slot create`
`slot remove <name>`	`name`	hidden, deprecated alias for `slot delete`
`slot show <name>`	`name`	`--json`
`slot metrics [name]`	optional `name`	`--json`
`slot capacity`	—	`--json`
`slot migrate-id-keying`	—	`--apply` (default: dry-run), `--yes`/`-y`, `--stop-services`
`slot migrate-hw`	—	`--apply`, `--yes`/`-y`, `--stop-services`
`slot migrate-caps`	—	`--apply`, `--yes`/`-y`, `--stop-services`
`slot migrate-flags`	—	`--apply`, `--yes`/`-y`, `--stop-services`
`slot migrate-enabled-removal`	—	`--apply`

`hal0 model` — manage the local model registry

Command	Args	Flags
`model list`	—	`--json`
`model pull <ref>`	`ref`	`--cancel`
`model default <ref>`	`ref`	`--clear`
`model update [ref]`	optional `ref`	`--check`, `--refresh` (only meaningful with `--check`)
`model register <model_id>`	`model_id`	hidden, deprecated alias for `model add`: `--path`/`-p` (required), `--name`, `--license` (default `unknown`)
`model rm <ref>`	`ref`	`--force`/`-f`
`model show <ref>`	`ref`	`--json`
`model assign <ref>`	`ref`	hidden, deprecated alias for `slot edit --model`: `--slot`/`-s` (required)
`model scan`	—	—
`model add <path>`	`path`	`--id` (default `""`), `--name`, `--license` (default `""`), `--overwrite`
`model store [path]`	optional `path`	`--migrate`
`model run <ref>`	`ref`	`--slot`/`-s` (default `""`), `--timeout` (default `300`)
`model import-backup <path>`	`path` (required)	`--force`/`-f`, `--dest` (default `/var/lib/hal0/registry/registry.toml`)

`hal0 memory` — manage hal0 memory (Hindsight engine)

Command	Args	Flags
`memory status`	—	`--json`
`memory enable`	—	`--json`
`memory disable`	—	`--json`
`memory recall <query>`	`query`	`--bank`, `--tags` (repeatable), `--types` (repeatable), `--max-tokens` (default `4096`), `--json`
`memory graph status`	—	`--json`
`memory graph enable`	—	`--slot`, `--json`
`memory graph disable`	—	`--json`

`memory bank`

Command	Args	Flags
`bank list`	—	`--json`
`bank stats <bank>`	`bank`	`--json`
`bank profile get <bank>`	`bank`	`--json`
`bank profile set <bank>`	`bank`	`--retain-mission`, `--observations-mission`, `--reflect-mission`, `--skepticism`/`--literalism`/`--empathy` (1-5), `--json`
`bank export <bank>`	`bank`	`--out`
`bank import <bank>`	`bank`	`--file` (required), `--dry-run`, `--json`
`bank delete <bank>`	`bank`	`--confirm` (required, must equal the bank id), `--json`
`bank consolidate <bank>`	`bank`	`--scope` (repeatable), `--json`

`memory ops`

Command	Args	Flags
`ops list`	—	`--bank` (omit = all banks), `--failed`, `--json`
`ops retry`	—	`--bank`, `--all-failed`, `--id` (requires `--bank`) — exactly one of `--all-failed`/`--id` required, `--json`

`memory mm` (mental models)

Command	Args	Flags
`mm list <bank>`	`bank`	`--json`
`mm refresh <bank> <model_id>`	`bank`, `model_id`	`--json`
`mm history <bank> <model_id>`	`bank`, `model_id`	`--json`

`memory migrate unify`

hal0 memory migrate unify --source BANK [--source BANK ...] [--target shared]
                           [--apply|--dry-run] [--add-tag TAG ...]
                           [--on-conflict skip|replace|new-id] [--skip-observations] [--json]

--source is repeatable and required. --target defaults to "shared". Defaults to dry-run unless --apply is given. --on-conflict defaults to skip.

`hal0 config` — inspect and manage configuration

ConfigFile enum: hal0|upstreams|providers.

Command	Args	Flags
`config show [which]`	optional `which` (default `hal0`)	—
`config edit [which]`	optional `which` (default `hal0`)	opens `$EDITOR`/`$VISUAL`/`vi`
`config migrate`	—	—
`config validate`	—	—
`config reload`	—	—
`config hardware`	—	`--refresh` — equivalent to the deprecated `hal0 probe`

`hal0 doctor` — diagnostics and repair

Bare hal0 doctor (no subcommand) runs installer/lib/preflight.sh: --verify (hidden, deprecated — use doctor verify), --plain (force ASCII, sets HAL0_PLAIN=1), --ports (space-separated TCP port list override).

Command	Flags
`doctor verify`	`--json`
`doctor logs`	`--unit` (default `hal0-api`), `--follow`/`-f`, `--lines`/`-n` (default `200`, 1-5000), `--level`, `--since`
`doctor toolbox-pull`	`--json`, `--manifest`
`doctor perms`	`--fix`, `--force`/`-f`, `--table-root` (audit old root-era table), `--json`
`doctor models`	`--fix`, `--force`/`-f`, `--json`
`doctor migrations`	`--json`
`doctor profiles`	`--json`
`doctor all`	`--json`
`doctor bundle`	`--out`, `--no-rocm-smi`, `--include-logs` (default `auto`; `auto\|yes\|no`)

`hal0 upstream` — manage upstream LLM providers

Command	Args	Flags
`upstream list`	—	`--json`
`upstream advertise <name> <state>`	`name`, `state` (`on\|off`)	—
`upstream show <name>`	`name`	`--json`
`upstream create <name>`	`name`	`--catalog`/`-c`, `--url`/`--base-url`, `--auth-style` (`bearer\|anthropic\|google_query\|header\|none`), `--auth-header`, `--auth-env`, `--timeout`, `--api-key`/`-k`, `--advertise-models`/`--hide-models` (default advertise), `--enabled`/`--disabled` (default enabled)
`upstream update <name>`	`name`	same as `create` (partial update) plus `--model` (repeatable), `--include` (repeatable), `--exclude` (repeatable), `--clear-filters`
`upstream delete <name>`	`name`	`--force`/`-f`
`upstream test <name>`	`name`	—
`upstream credentials set <name>`	`name`	`--key` (required, prompts securely if omitted), `--env-var`
`upstream set-credentials <name>`	`name`	hidden, deprecated alias for `upstream credentials set`

`hal0 capabilities` — capability-slot configuration

Command	Args	Flags
`capabilities list`	—	—
`capabilities set <slot> <child>`	`slot`, `child`	`--model`, `--backend`, `--provider`, `--enabled`/`--disabled`
`capabilities migrate`	—	`--apply` (default: dry-run), `--dry-run` (hidden, deprecated no-op)

`hal0 comfyui`

Command	Flags
`comfyui orchestrate-models`	`--dry-run`, `--log-dir` (default `""`)

`hal0 agent` — manage bundled agents

Command	Args	Flags
`agent install <name>`	`name` (e.g. `hermes`)	`--switch`, `--gateway`/`--no-gateway` (default gateway), `--reset-personas`
`agent uninstall <name>`	`name`	`--keep-memory`, `--force`/`-f`
`agent list`	—	`--json`
`agent peers`	—	—
`agent status [name]`	optional `name` (default `hermes`)	`--json`
`agent log [name]`	optional `name` (default `hermes`)	`--phase`
`agent upgrade [name]`	optional `name` (default `hermes`)	`--to`
`agent reprovision [name]`	optional `name` (default `hermes`)	`--repair`, `--verbose`/`-v`
`agent approvals list`	—	—
`agent approvals approve <approval_id>`	`approval_id`	—
`agent approvals deny <approval_id>`	`approval_id`	—
`agent bootstrap hermes`	—	`--repair`, `--dry-run`, `--skip-phase` (repeatable), `--offline`, `--verbose`/`-v`
`agent personas list`	—	—
`agent personas show <persona_id>`	`persona_id`	—
`agent personas activate <persona_id>`	`persona_id`	`--reload-url`

`hal0 app` — manage optional apps

Command	Args	Flags
`app install <name>`	`name` (currently only `openwebui`)	—
`app list`	—	—
`app uninstall <name>`	`name`	`--force`/`-f`

`hal0 migrate` — one-shot v0.2 layout migrations

Command	Flags
`migrate model-layout`	`--apply` (default: dry-run), `--force`/`-f`, `--registry` (default `/var/lib/hal0/registry/registry.toml`), `--mount-root` (default `/mnt/ai-models`), `--canonical-root` (default `/var/lib/hal0/models`)

`hal0 registry` — inspect and repair the model registry

Command	Args	Flags
`registry import <path>`	`path`	hidden, deprecated alias for `model import-backup`: `--force`/`-f`, `--dest`
`registry export`	—	`--out` (default: canonical registry path)
`registry import-sqlite`	—	`--registry-file` (default: canonical registry path)

`hal0 profile` — inspect launch-flag profiles

Read-only: full CRUD (create/update/delete/generate/import/export) is dashboard/API-only (/api/profiles).

Command	Args	Flags
`profile list`	—	`--json`
`profile show <name>`	`name`	`--json`

`hal0 mcp` — manage MCP servers

Command	Args	Flags
`mcp list`	—	`--json`
`mcp status <server_id>`	`server_id`	`--json`
`mcp install <url_spec>`	`url_spec`	`--json`
`mcp uninstall <server_id>`	`server_id`	`--force`/`-f`
`mcp restart <server_id>`	`server_id`	—
`mcp catalog list`	—	`--json`
`mcp catalog refresh`	—	`--json`

`hal0 auth` — manage hal0 API authentication

KeyTier enum: admin|client. RequireToggle enum: on|off.

Command	Args	Flags
`auth status`	—	`--json`
`auth rotate [tier]`	optional `tier` (default `admin`)	`--force`/`-f`
`auth require <toggle>`	`toggle` (required)	—

`hal0 board` — operator task board

Command	Args	Flags
`board list`	—	`--board`, `--include-archived`, `--json`
`board show <task_id>`	`task_id`	`--json`
`board add <title>`	`title`	`--body` (default `""`), `--assignee` (default `""`), `--status` (default `triage`), `--board`, `--priority` (default `0`)
`board move <task_id> <status>`	`task_id`, `status`	—

Deprecated aliases

All hidden and tagged HAL0-SUNSET: v1.0.0 — still work, but don’t script against them:

Deprecated	Use instead
`hal0 probe`	`hal0 config hardware --refresh`
`hal0 model register`	`hal0 model add`
`hal0 model assign`	`hal0 slot edit --model`
`hal0 slot add`	`hal0 slot create`
`hal0 slot remove`	`hal0 slot delete`
`hal0 registry import`	`hal0 model import-backup`
`hal0 upstream set-credentials`	`hal0 upstream credentials set`

`hal0-agent` (separate binary)

Not part of the hal0 app — a standalone argparse binary invoked by hal0-agent@<id>.service, not intended for direct interactive use:

hal0-agent <agent_id> serve|stop|status|reprovision|render-context

hal0 CLI reference

Global

Top-level commands

hal0 setup

hal0 update

hal0 slot — manage inference slots

hal0 model — manage the local model registry

hal0 memory — manage hal0 memory (Hindsight engine)

memory bank

memory ops

memory mm (mental models)

memory migrate unify

hal0 config — inspect and manage configuration

hal0 doctor — diagnostics and repair

hal0 upstream — manage upstream LLM providers

hal0 capabilities — capability-slot configuration

hal0 comfyui

hal0 agent — manage bundled agents

hal0 app — manage optional apps

hal0 migrate — one-shot v0.2 layout migrations

hal0 registry — inspect and repair the model registry

hal0 profile — inspect launch-flag profiles

hal0 mcp — manage MCP servers

hal0 auth — manage hal0 API authentication

hal0 board — operator task board