CLI Reference
The hoziron-cli command-line interface is the primary operator tool for managing the Hoziron platform.
Installation
# Download the latest release (Linux x86_64 example)
TARGET="x86_64-unknown-linux-gnu"
curl -sSL "https://dl.hoziron.com/latest/hoziron-${TARGET}.tar.gz" -o hoziron-cli.tar.gz
tar -xzf hoziron-cli.tar.gz
sudo mv hoziron-*/hoziron-cli /usr/local/bin/
rm -rf hoziron-cli.tar.gz hoziron-*/
See Install via Binary for the full list of available targets.
Global Flags
These flags apply to all commands:
| Flag | Description |
|---|---|
--config <path> | Path to config file (default: ~/.hoziron/config.toml) |
--context <name> | Use a specific context for this command (overrides current_context) |
--help | Show help for any command |
--version | Show version information |
Command Overview
| Command | Description | Reference |
|---|---|---|
init | Initialize config directory | init.md |
agent | Manage agents (list, status, activate, suspend, chat, set) | agent.md |
workflow | Run and inspect workflows (list, get, run, runs, status) | workflow.md |
competency | Manage competencies (install, activate, configure) | competency.md |
package | Package authoring (init, build, inspect, lint, verify, publish, provenance) | package.md |
catalog | Catalog discovery and installation | catalog.md |
collection | Curated bundles of catalog packages (init, list, install, inspect, publish, validate) | collection.md |
config | Configuration management | config.md |
context | Multi-instance context switching | context.md |
channel | Channel integrations (Slack, Teams, etc.) | channel.md |
skill | Skill management | skill.md |
memory | Agent memory (KV store) | memory.md |
cron | Scheduled jobs | cron.md |
auth | API key management | auth.md |
login / logout / whoami | OIDC session login and identity | auth.md |
security | Security tools and audit | security.md |
models | Model and alias browsing | models.md |
providers | LLM provider management (list, create, enable, disable) | providers.md |
integration | Integration server lifecycle (connect, disconnect, reconnect) | integration.md |
add / remove / integrations | One-shot integration install/remove/search helpers | integration.md |
vault | Credential vault | vault.md |
contract | Inspect recorded contract bindings (read-only) | contract.md |
licence | Licence status (ADR-034) | licence.md |
backup | Platform state backup and restore | backup.md |
system | CLI/system info and version | system.md |
agent chat <id> | Interactive chat with an agent (see agent.md) | agent.md |
sessions | List conversation sessions | utilities.md |
status | Show kernel status | utilities.md |
health | Quick health check | utilities.md |
doctor | Run diagnostics | utilities.md |
logs | Tail daemon logs | utilities.md |
dashboard | Open web dashboard | utilities.md |
completion | Generate shell completion scripts | utilities.md |
onboard | Interactive onboarding wizard | utilities.md |
reset | Reset local state | utilities.md |
uninstall | Remove Hoziron from system | utilities.md |
Quick Start Examples
# Initialize the CLI config, start the server (separate process — see
# start-stop.md), then point the CLI at it
hoziron-cli init
hoziron-server &
hoziron-cli context add local --url http://127.0.0.1:4200
hoziron-cli context use local
# Install an agent-template package (this is how agents are created — see
# agent.md#creating-an-agent), then chat with it by ID (there is no default
# agent — the platform ships empty, nothing runs until installed)
hoziron-cli catalog install assistant-template --activate
hoziron-cli agent list
hoziron-cli agent chat <agent-id>
# Check health
hoziron-cli health
# Fetch recent logs (one-shot fetch — --follow is currently a no-op, see utilities.md#logs)
hoziron-cli logs
Output Formats
Most commands support --json for machine-readable output. Response shapes
vary by command — check the specific page for the exact field names (many
wrap results in a named key like {"agents": [...]} rather than returning a
bare array):
# Human-readable (default)
hoziron-cli agent list
# JSON (for scripting/piping)
hoziron-cli agent list --json | jq -r '.agents[] | .name'
Environment Variables
| Variable | Purpose | Default |
|---|---|---|
HOZIRON_HOME | Config/data directory | ~/.hoziron |
HOZIRON_LOG | Log level filter | info |
HOZIRON_LOG_FORMAT | Log format (text or json) | text |
There is no HOZIRON_LISTEN env var — the daemon's listen address is set via
hoziron-server --api-listen <addr> or [surfaces.api].listen in
config.toml. See start-stop.md.
hoziron-cli onboard --quick additionally reads HOZIRON_URL, HOZIRON_CONTEXT,
and HOZIRON_API_KEY — see utilities.md#onboard.
Interactive Launcher
Running hoziron-cli with no subcommand in an interactive terminal shows a branded launcher menu:
? What would you like to do?
→ Get Started (runs init)
→ Chat
→ Dashboard
→ Terminal UI
→ Show Help
→ Quit
In non-interactive mode (piped), it prints help text.