Skip to main content
Run HoloDesktop CLI commands from the holo-desktop checkout: 
uv run holo --help

​
Commands

CommandPurpose
holo runRun one foreground task on the visible desktop.
holo mcpRun the stdio MCP server.
holo acpRun the stdio ACP server.
holo installWire HoloDesktop CLI into a supported host.
holo loginSign in to H Company for hosted mode.
holo whoamiPrint the cached hosted-mode identity.
holo doctorDiagnose runtime, login, agent API, permissions, and ~/.holo.
holo stopRequest that the active run stop.
holo guardRun the double-Esc listener used by headless host surfaces.

​
Run

uv run holo run "Open TextEdit and write a short note saying HoloDesktop CLI is installed"
Useful options:
OptionPurpose
--base-url URLUse a local OpenAI-compatible model endpoint.
--model NAMESelect the hosted model ID or local model ID.
--max-steps NStop after at most N agent steps.
--max-time-s SECONDSStop after a wall-clock timeout.
--runs-dir DIRWrite runtime run logs somewhere other than the binary default.
--port PORTUse a non-default agent API port. Defaults to 18795.
--quietPrint only the final answer.
--profilePrint timing output from the runtime event log at exit.
--expandPrint every step as a full panel.
Hosted mode: 
uv run holo run \
  --model holo3-1-35b-a3b \
  "Open TextEdit and write a short note saying HoloDesktop CLI is installed"
Local mode: 
uv run holo run \
  --base-url http://localhost:8000/v1 \
  --model Hcompany/Holo-3.1-35B-A3B \
  "Open TextEdit and write a short note saying HoloDesktop CLI is installed"
If a runtime is already listening on the same port, --model, --base-url, --runs-dir, and --fake require a fresh runtime. Stop the existing runtime or pass a different --port.

​
Stop

uv run holo stop
holo stop writes a local stop signal that the active run checks while it is streaming events. This is the terminal fallback for CLI, MCP, ACP, and other host-launched runs. Force stop only when the normal stop request does not respond: 
uv run holo stop --force
--force kills the runtime process. It is the instant stop path, but it can leave a host-side MCP or ACP call in an error state until the host is restarted or retries the tool call. During an interactive holo run, you can also press Esc twice quickly. Double-Esc sends the same stop signal, then the run pauses and cancels at the next safe point.

​
Guard

uv run holo guard
holo guard listens for double-Esc outside an interactive terminal run. It is mainly used by headless surfaces such as MCP and ACP, where the host process owns stdio and the user may not have terminal focus. holo install can install the guard as an OS-level startup service for supported platforms. On macOS, grant Input Monitoring to the guard when prompted so the double-Esc listener can receive key events.

​
MCP

uv run holo mcp
This command is normally launched by an MCP host, not typed directly. It uses stdio and auto-spawns hai-agent-runtime if no healthy runtime is already listening. Use Use HoloDesktop CLI as an MCP server for host setup.

​
ACP

uv run holo acp
This command is normally launched by an ACP host. It uses stdio and spawns the runtime on first use. Use Use HoloDesktop CLI as an ACP sub-agent for host setup.

​
Install

uv run holo install claude-code
For Claude Code, run this from the workspace where you want HoloDesktop CLI registered. Claude Code’s MCP configuration is workspace-scoped.

​
Login

uv run holo login
holo login opens a browser sign-in flow, saves HAI_API_KEY to ~/.holo/.env, and writes an identity cache to ~/.holo/profile.json. Rotate or switch identity: 
uv run holo login --force

​
Whoami

uv run holo whoami
This reads local identity state and prints the signed-in account. It exits non-zero if no hosted-mode identity is available.

​
Doctor

uv run holo doctor
doctor is read-only. Use it when setup, runtime launch, credentials, permissions, or the agent API are failing.