CLI reference

Run HoloDesktop CLI commands with the holo command. From a source checkout, prefix commands with uv run.

holo --help

Commands

Command	Purpose
`holo run`	Run one foreground task on the visible desktop.
`holo stop`	Stop the running turn; `--force` also kills the runtime.
`holo mcp`	Run the stdio MCP server.
`holo acp`	Run the stdio ACP server.
`holo serve`	Run the A2A HTTP server on loopback.
`holo guard`	Run the double-`Esc` kill switch in the foreground.
`holo install`	Wire HoloDesktop CLI into a supported host.
`holo login`	Sign in to H for hosted mode.
`holo whoami`	Print the cached hosted-mode identity.
`holo doctor`	Diagnose runtime, login, agent API, permissions, and `~/.holo`.

Run

holo run "Open TextEdit and write a short note saying HoloDesktop CLI is installed"

Useful options:

Option	Purpose
`--base-url URL`	Use a local OpenAI-compatible model endpoint.
`--model NAME`	Select the hosted model ID or local model ID.
`--max-steps N`	Stop after at most `N` agent steps.
`--max-time-s SECONDS`	Stop after a wall-clock timeout.
`--fast`	One screenshot per step, no thinking, smaller uploads. Faster, lower quality.
`--no-kill-switch`	Skip the double-`Esc` listener for this run (and the macOS Input Monitoring prompt).
`--runs-dir DIR`	Write runtime run logs somewhere other than the binary default.
`--port PORT`	Use a non-default agent API port. Defaults to `18795`.
`--quiet`	Print only the final answer.
`--profile`	Print timing output from the runtime event log at exit.
`--expand`	Print every step as a full panel.

Hosted mode:

holo run \
  --model holo3-1-35b-a3b \
  "Open TextEdit and write a short note saying HoloDesktop CLI is installed"

Local mode:

holo run \
  --base-url http://localhost:8000/v1 \
  --model holo3-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, and --runs-dir require a fresh runtime. Stop the existing runtime or pass a different --port.

Stop a run

Esc twice, Ctrl+C in the launching terminal, or holo stop from any terminal. holo stop --force also kills the runtime. Details in Stop a run.

holo guard

The double-Esc listener for headless surfaces (holo mcp, holo acp, holo serve). holo install registers it with the OS so it runs on its own permission identity; run it by hand only if you skipped holo install. It inspects Esc timing only, never keystroke content.

MCP

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 Agent hosts for host setup.

ACP

holo acp

This command is normally launched by an ACP host. It uses stdio and spawns the runtime on first use. Use Agent hosts for host setup.

Serve

holo serve

An A2A server on 127.0.0.1:18794 for your own agents. Each A2A contextId maps to one agent session. Protect it with a bearer token in HOLO_AUTH_TOKEN.

Option	Purpose
`--port PORT`	Listen on a different loopback port.
`--base-url URL`, `--model NAME`	Same as `holo run`.
`--cors-origin ORIGIN`	Allow an extra browser origin. Repeatable.

Use Agent hosts for client setup.

Install

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.

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:

holo login --force

Whoami

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

holo doctor

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

Get started

Integrations

How-to guides

Reference

Examples

Commands

Run

Stop a run

MCP

ACP

Serve

Install

Whoami

Doctor

Next steps

Environment variables

Debug a failed run

​Commands

​Run

​Stop a run

​MCP

​ACP

​Serve

​Install

​Login

​Whoami

​Doctor

​Next steps

Environment variables

Debug a failed run

Commands

Run

Stop a run

MCP

ACP

Serve

Install

Login

Whoami

Doctor

Next steps