Utility Commands

Standalone commands for day-to-day operations — chat, diagnostics, logs, and system management.

chat

Interactive chat with an agent lives under hoziron-cli agent chat <id> — see agent.md. There is no top-level chat shortcut and no default agent: the platform ships empty and inert, so an agent ID is always required explicitly.

For non-interactive, scripted sends, call the REST API directly:

curl -X POST -H "Authorization: Bearer $HOZIRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "How many open claims are there?"}' \
  http://localhost:4200/agents/{id}/send

status

Reads and validates the local config.toml directly — it does not contact a running daemon at all, so it works even when no hoziron-server is up. It reports config validity, the resolved local model, and provider auth readiness.

hoziron-cli status [--json]

Example

$ hoziron-cli status
Hoziron Platform Status
────────────────────────────────────────
  Config:     ✓ valid
  Local model: ollama / llama3.1:70b
  Providers:  3/4 ready
  Health:     enabled (interval: 30s)

# No config found yet
$ hoziron-cli status
Hoziron Platform Status
────────────────────────────────────────
  Config:     ✗ not found (run: hoziron-cli init)

$ hoziron-cli status --json
{
  "config_exists": true,
  "config_valid": true,
  "providers": [
    {"id": "anthropic", "status": "Configured", "models": 2},
    {"id": "groq", "status": "Configured", "models": 3},
    {"id": "ollama", "status": "NotRequired", "models": 1}
  ]
}

health

Identical to hoziron-cli status — dispatch_health is a direct alias for the same config-validation-and-provider-auth check, not a call to a running daemon's /health endpoint. There is no separate agent/uptime/memory health summary at the CLI layer; use hoziron-cli doctor for CLI-side filesystem checks, or query the daemon's health surface directly (see ../api/health-status.md) for daemon-side health.

hoziron-cli health [--json]

Example

$ hoziron-cli health
Hoziron Platform Status
────────────────────────────────────────
  Config:     ✓ valid
  Local model: ollama / llama3.1:70b
  Providers:  3/4 ready
  Health:     enabled (interval: 30s)

doctor

Run local diagnostic checks against the CLI's own config/data directories. This does not check daemon reachability, provider connectivity, or signing keys — it is a pure filesystem/config sanity check, run entirely client-side with no network calls.

hoziron-cli doctor [--repair] [--json]

Checks performed

Exactly four, in this order:

Flags

Example

$ hoziron-cli doctor
Hoziron Doctor
──────────────────────────────────────────────────
  ✓ Home directory        /root/.hoziron
  ✓ Config file            /root/.hoziron/config.toml
  ✗ Data directory         /root/.hoziron/data
  ✓ Provider auth          At least one provider configured

Some checks failed.
  Run with --repair to auto-fix issues.

# Auto-repair — only creates missing directories, and points at `init`
# for a missing/invalid config.toml rather than writing one itself
$ hoziron-cli doctor --repair
Hoziron Doctor
──────────────────────────────────────────────────
  ✓ Home directory        /root/.hoziron
  ✓ Config file            /root/.hoziron/config.toml
  ✗ Data directory         /root/.hoziron/data
  ✓ Provider auth          At least one provider configured

Some checks failed.
  Repaired: created /root/.hoziron/data

$ hoziron-cli doctor --json
[
  {"check": "Home directory", "pass": true, "detail": "/root/.hoziron"},
  {"check": "Config file", "pass": true, "detail": "/root/.hoziron/config.toml"},
  {"check": "Data directory", "pass": true, "detail": "/root/.hoziron/data"},
  {"check": "Provider auth", "pass": true, "detail": "At least one provider configured"}
]

logs

Fetch recent logs from the API server via GET /logs?lines=<n>. This is a single request-response fetch, not a live tail.

hoziron-cli logs [--lines <n>] [--follow]

Flags

If the server doesn't expose a /logs endpoint (older server version, or the surface simply doesn't implement it), the CLI prints a clear fallback message rather than an error.

Examples

# Show last 50 lines
$ hoziron-cli logs
2026-06-04T10:15:02 INFO agent.send_message agent_id=550e8400 model=anthropic/claude-sonnet-4-20250514
2026-06-04T10:15:04 INFO agent.send_message.complete tokens_used=342 latency_ms=2100

# Show last 100 lines
$ hoziron-cli logs --lines 100

# --follow is currently a no-op — this exits immediately after one fetch,
# it does not keep streaming
$ hoziron-cli logs --follow

# Server doesn't support /logs
$ hoziron-cli logs
Could not retrieve logs from the API server.
The /logs endpoint may not be available on this server version.

For an actual live tail, read the server's log file/stdout directly (e.g. journalctl -u hoziron -f under systemd, or docker logs -f <container>).

dashboard

Open the active context's dashboard URL in the default browser. First verifies the daemon is reachable (GET /health) before opening anything.

$ hoziron-cli dashboard
Opening dashboard at http://127.0.0.1:4200

If no context is configured, it falls back to http://127.0.0.1:4200.

sessions

List conversation sessions — GET /sessions (all agents) or GET /agents/{agent}/sessions (filtered).

hoziron-cli sessions [agent] [--json]

Example

$ hoziron-cli sessions
ID                                     AGENT                STARTED
sess-a1b2c3d4-e5f6-7890-abcd-ef123456  claims-agent         2026-07-08T09:12:00Z
sess-e5f6a7b8-9012-cdef-1234-56789012  assistant-01         2026-07-08T08:05:00Z

$ hoziron-cli sessions claims-agent
ID                                     AGENT                STARTED
sess-a1b2c3d4-e5f6-7890-abcd-ef123456  claims-agent         2026-07-08T09:12:00Z

$ hoziron-cli sessions --json
{
  "sessions": [
    {"id": "sess-a1b2c3d4-e5f6-7890-abcd-ef123456", "agent_id": "claims-agent", "started_at": "2026-07-08T09:12:00Z"}
  ]
}

system

System information — moved to its own reference page: see system.md for hoziron-cli system info and hoziron-cli system version.

completion

Generate shell completion scripts.

hoziron-cli completion <shell>

Supported Shells

bash, zsh, fish, elvish, powershell

Examples

# Bash
$ hoziron-cli completion bash > ~/.local/share/bash-completion/completions/hoziron-cli

# Zsh
$ hoziron-cli completion zsh > ~/.zfunc/_hoziron-cli

# Fish
$ hoziron-cli completion fish > ~/.config/fish/completions/hoziron-cli.fish

onboard

Interactive wizard that connects the CLI to a running Hoziron API server — not a provider/LLM-key setup wizard (that's server-side config, see config.md). The API key this wizard asks about is a Hoziron platform API key for authenticating the CLI to the daemon (HOZIRON_API_KEY / hoziron-cli auth create-key), unrelated to Anthropic/OpenAI/etc. provider keys.

hoziron-cli onboard [--quick]

Flags

The 5 interactive steps

1. Initialize — ensure $HOZIRON_HOME/config.toml exists (same as hoziron-cli init).
2. Connect — prompt for the API server URL (default http://127.0.0.1:4200 on Enter) and a name for the context; offers to reuse an existing context if any are already configured.
3. Authenticate — if HOZIRON_API_KEY is already set in the environment, uses it automatically; otherwise asks whether the server requires a key and, if so, whether to reference an env var or paste the key now (saved to $HOZIRON_HOME/.env, file mode 0600).
4. Verify — calls the server's health endpoint and prints version/uptime/agent counts if reachable.
5. Test — lists agents on the server as a final sanity check and suggests hoziron-cli agent chat <id> next.

--quick (non-interactive)

--quick skips all prompts and is driven entirely by environment variables:

Examples

$ hoziron-cli onboard
  Hoziron CLI Setup — connect to your Hoziron API server
  ──────────────────────────────────────────────────
  Step 1/5 Checking local configuration...
  ✓ Created /root/.hoziron/config.toml

  Step 2/5 Where is your Hoziron API server?
  Enter the API server URL (or press Enter for local dev):
    Default: http://127.0.0.1:4200
  URL: [Enter]
  Name this connection (default: local):
  Context name: [Enter]

  Step 3/5 Authentication
  Does your API server require an API key?
    (If unsure, try without — you can add one later)
  Configure API key? [y/N]: n
  → Skipping auth (no API key configured)

  Step 4/5 Verifying API server connectivity...
  ✓ API server is healthy
  ℹ Server version: 0.6.0
  ℹ Uptime: 0h 3m
  ℹ Agents: 2 total, 2 running

  Step 5/5 Testing agent communication...
  ✓ Agents on this server:

    NAME                 STATE        ID
    assistant-01         Running      550e8400
    claims-processor     Running      7c9e6679

  Try chatting: hoziron-cli agent chat 550e8400

# Non-interactive, CI/automation
$ HOZIRON_URL=https://hoziron.staging.internal HOZIRON_API_KEY=hzn_sk_*** hoziron-cli onboard --quick
Running quick setup (non-interactive)...
✓ Context 'default' → https://hoziron.staging.internal
✓ API server is healthy.
✓ Quick setup complete.

reset

Reset CLI configuration only — contexts and API keys. Despite the name, it does not touch $HOZIRON_HOME/data/ (agents, memory, sessions live on the daemon, not the CLI, and this command never talks to a daemon). Without --confirm it prints what it would do and exits — there is no interactive [y/N] prompt to answer.

hoziron-cli reset [--confirm]

Concretely, --confirm does two things: deletes $HOZIRON_HOME/.env (if present) and overwrites config.toml with a one-line placeholder.

Example

# Without --confirm: prints what would happen, changes nothing
$ hoziron-cli reset
This will reset CLI configuration in /root/.hoziron
Removes: contexts, .env, and resets config.toml to defaults.
Run with --confirm to proceed.

# With --confirm: actually resets
$ hoziron-cli reset --confirm
✓ CLI configuration reset.
  Re-run `hoziron-cli onboard` to set up a new connection.

uninstall

Remove the CLI's local directory. Like every other CLI command, this makes no attempt to stop a running hoziron-server — the CLI is a pure HTTP client and never manages the server process (see start-stop.md). Without --confirm/--yes it prints what it would do and exits — there is no interactive prompt.

hoziron-cli uninstall [--confirm] [--keep-config]

Flags

Example

# Without --confirm: prints what would happen, changes nothing
$ hoziron-cli uninstall
This will completely remove Hoziron from /root/.hoziron
Run with --confirm (or --yes) to proceed.

# Full removal
$ hoziron-cli uninstall --confirm
Hoziron completely uninstalled.

# Keep config for potential reinstall — only data/ is removed
$ hoziron-cli uninstall --confirm --keep-config
Uninstalled (config files preserved).

If you also need to stop a running server, do that separately (see start-stop.md) — uninstall does not do it for you.