Holo CLI reference - H Platform Docs

Commands

holo --help lists every command, and holo <command> --help its options.

Command	Purpose
`holo "task"`, `holo run "task"`	Run one task and print the answer. Follow-ups continue the session in a terminal
`holo`, `holo chat`	Start an interactive chat session
`holo login`	Sign in in the browser, and save an API key to `~/.config/hai/.env`. Does nothing if a key is already available
`holo logout`	Remove the saved API key. A key exported in your shell is unaffected
`holo whoami`	Print the endpoint and where the API key comes from
`holo doctor`	Diagnose login, platform access, the local runtime, local browser and desktop control, and the macOS grants of the app running it. Read-only
`holo agents list`, `get`, `use`	Browse agents, and set the default one
`holo skills list`, `get`	Browse platform skills
`holo sessions list`, `get`, `status`, `events`, `watch`	Inspect sessions
`holo sessions send`, `cancel`, `share`, `unshare`	Steer and share sessions
`holo mcp`	Run the local MCP server for coding agents. Hosts start it
`holo mcp install [host]`	Add `holo mcp` to a host, or with `--remote` the hosted MCP server
`holo local stop`	Stop every run driving this machine, like the double-`Esc` kill switch
`holo local browser`, `desktop`	Serve this machine to a cloud agent loop, with holo local

Global options

Put these before the command, as in holo --json sessions list.

Option	Purpose
`--api-key KEY`	API key. Defaults to `HAI_API_KEY`
`--base-url URL`	Agent Platform URL. Defaults to `HAI_API_BASE_URL`, else the EU platform
`--json`	Print machine-readable JSON

Run

holo run "Open Hacker News and list the top 3 stories with their URLs."

Option	Purpose
`--agent NAME`, `-a`	Agent to run. Defaults to `h/web-surfer-flash`, or the one set with `holo agents use`. `NAME:N` pins revision `N`
`--local`	Run the agent loop on this machine, through the local runtime
`--max-steps N`	Stop after at most `N` agent steps. Uncapped by default, or `150` for a run that drives this machine
`--max-time SECONDS`	Stop after a wall-clock timeout. Uncapped by default, or `1800` for a run that drives this machine
`--quiet`, `-q`	Print only the final answer
`--override PATH=VALUE`, `-o`	Per-run override, repeatable. `VALUE` is parsed as JSON, else a string

Chat

holo chat, or holo alone, takes --agent and --local.

Key or command	Does
Type, then `Enter`	Message the agent while it works
`Esc`	Pause the agent. `Esc` again resumes
`/answer`	Make it answer now
`Ctrl+C`	Cancel the turn, or clear the input. Twice to leave
`Ctrl+D`, `/exit`	Leave
`Up`, `Down`, `Ctrl+R`	Browse and search previous messages
`Tab` or `→`	Accept the grey suggestion
`\` then `Enter`	New line
`/new [task]`	Start a new session
`/retry`	Run the first task again in a new session
`/resume [n]`	Continue a recent session
`/agent [name]`	Switch agent and save it as the default
`/live`, `/share`	Open the live view, or create a public link
`/status`, `/copy`	Show session and usage, or copy the last answer

A session stays open for 10 minutes after each answer.
While an agent drives this machine, your typing goes to your apps, so the prompt only listens for Esc twice.
With --local, /resume, /live, and /share are off, since they need a cloud session.

Option	Does
`--force`	Sign in again and rotate the saved key
`--key`	Save a key from platform.hcompany.ai/settings/api-keys, read from a hidden prompt or from stdin

holo local

Serves this machine to a cloud agent loop. Not --local. Use these commands for a session started elsewhere, such as a registered agent or the web app. Each prints the session ID it serves: set it on the agent’s user_device environment, as in Your browser and Your desktop.

Command	Serves	Install extra
`holo local browser`	Chrome on this machine	`browser`
`holo local desktop`	This machine’s mouse, keyboard, and screen	`desktop`

Flag	Command	Default	Meaning
`--session-id`	Both	Generated	Session ID to serve
`--debug-port`	`browser`	`9222`	Chrome remote-debugging port to attach to
`--max-width`	`desktop`	`1920`	Cap screenshot width in pixels. `0` disables
`--max-height`	`desktop`	`0`	Cap screenshot height in pixels. `0` disables
`--image-format`	`desktop`	`jpeg`	`png`, `jpeg`, or `webp`
`--quality`	`desktop`	`85`	Encoding quality, 1 to 100, for `jpeg` and `webp`

holo local desktop downscales and recompresses screenshots before upload. The desktop environment’s screenshot_max_width caps width again on the agent’s side, so the smaller limit applies. In an interactive terminal, holo local desktop also stops on Esc twice, with the same desktop permissions. If the kill switch cannot arm, it says so: use holo local stop.

Environment variables

Variable	Purpose
`HAI_API_KEY`	API key
`HAI_API_BASE_URL`	Agent Platform URL. Same as `--base-url`
`HAI_AGENT`	Default agent. Set by `holo agents use`
`HAI_AGENT_RUNTIME_BASE_URL`	With `--local`: your OpenAI-compatible model server, such as `http://localhost:8000/v1`. Your H API key is never sent to it
`HAI_AGENT_RUNTIME_MODEL`	With `--local`: the model name sent to that server, such as `holo4-35b-a3b`
`HAI_AGENT_RUNTIME_PORT`	Loopback port of the local runtime. Defaults to `18795` for hosted inference. Each self-hosted server and model gets its own port
`HAI_AGENT_RUNTIME_API_TOKEN`	Bearer token for the local runtime. Generated when unset
`HAI_AGENT_LOCAL_BINARY_PATH`	Run this `hai-agent-runtime` executable
`HAI_AGENT_LOCAL_CACHE_DIR`	Runtime cache. Defaults to `~/.hai/agent-runtime`
`HAI_AGENT_RUNTIME_DOWNLOAD_URL`, `HAI_AGENT_RUNTIME_DOWNLOAD_SHA256`	Download a trusted runtime build. Set both or neither

HAI_API_KEY is read from, in order: --api-key, the process environment, then ~/.config/hai/.env. XDG_CONFIG_HOME, when set, replaces ~/.config.

Files

Treat all of these as sensitive.

Path	Purpose
`~/.config/hai/.env`	API key, default agent, and the endpoint `holo mcp install` saved
`~/.config/hai/stop`	Stop request written by `holo local stop` and the double-`Esc` kill switch. A run obeys only a stop filed after it started
`~/.config/hai/desktop.lock`	Held by the agent driving the desktop, so one runs at a time
`~/.holo/agents.md`	Standing instructions added to every run
`~/.holo/skills/<name>/SKILL.md`	Your skills, added to every run
`~/.hai/agent-runtime/logs/hai-agent-runtime-<port>.log`	Local runtime startup and error log
`~/.hai/agent-runtime/state/`	Each runtime’s owner-only token and what it infers against, so local clients share a runtime but never one serving another model

holo sends agents.md and your skills as the agent.instructions and agent.skills overrides. Your own -o overrides win. A skill’s directory name is its name. SKILL.md needs YAML frontmatter with a description, which the agent matches tasks against. A file without one stops the run with an error naming it. Only SKILL.md is read. A skill with the same name as one of the agent’s replaces it.

Runtime

--local resolves hai-agent-runtime in this order:

HAI_AGENT_LOCAL_BINARY_PATH
hai-agent-runtime on PATH
The managed install under ~/.hai/agent-runtime/bin/<version>/
A sha256-verified download of the pinned version, on first run

holo doctor shows which one it will use.

Platform	Download
macOS, Apple silicon	Yes
Windows, x86_64 and ARM64	Yes
Linux x86_64	Yes. Needs glibc 2.34+ (Ubuntu 22.04, Debian 12, RHEL 9)
Other platforms	No. Put your own `hai-agent-runtime` on `PATH`

Troubleshoot

Start with holo doctor. Fix the first failing row. If a coding agent’s run fails, try the smallest version in a terminal:

holo -a h/holo-desktop --max-steps 5 "Open TextEdit and write the word test"

If that works, the problem is the host: check that holo whoami finds a saved key, and that the host’s MCP env block has the variables you need. The terminal prints each step. Hosts get the same steps as MCP log messages. holo sessions events <session-id> shows a cloud session’s full history. With --local, the runtime logs to ~/.hai/agent-runtime/logs/. Logs can hold anything that was on screen, so read What the agent can see before you share them.

Symptom	Fix
`No API key found`	`holo login`
`API error 401`	The key is invalid: `holo login --force`
`Local desktop control requires hai-drivers>=0.1.2`	`pip install "hai-agents[cli,desktop]"`
`Local browser control requires extra deps`	`pip install "hai-agents[cli,browser]"`
`another agent is driving this desktop`	Wait for it, or run `holo local stop`
`... needs YAML frontmatter with a description`	Fix or remove that skill in `~/.holo/skills/`
Works in the terminal, not from the host	Run `holo login --force` so the key is saved, and set env vars in the host’s MCP config
Claude Code cannot see `holo`	`holo mcp install claude-code`, check `claude mcp get holo`, restart Claude Code
The agent cannot see the screen	Grant Screen Recording to the app that starts `holo`, then restart it
The agent sees but cannot click or type	Grant Accessibility, then restart the app
A run from a host will not stop	`Esc` twice, or `holo local stop`
The agent drives the wrong monitor	Move the app to the primary display
`the runtime at ... infers against ..., not ...`	Two inference settings share `HAI_AGENT_RUNTIME_PORT`. Unset it, or use one port each
`a runtime of unknown inference already listens there`	An older runtime holds the port. Stop it, or set `HAI_AGENT_RUNTIME_PORT` to a free port
The task times out	Make it smaller, or use a faster model

​Commands

​Global options

​Run

​Chat

​Login

​holo local

​Environment variables

​Files

​Runtime

​Troubleshoot