CLI reference - H Tech Hub

Run HoloDesktop CLI commands with the holo command. If you are developing from a source checkout instead of using the installer, 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 install`	Wire HoloDesktop CLI into a supported host.
`holo login`	Sign in to H Company for hosted mode.
`holo whoami`	Print the cached hosted-mode identity.
`holo doctor`	Diagnose runtime, login, agent API, permissions, and `~/.holo`.
`holo serve`	Run the local A2A server.

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.
`--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 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, and --runs-dir require a fresh runtime. Stop the existing runtime or pass a different --port.

Stop a run

While a foreground holo run is active, press Esc twice quickly to stop it. This is a global kill switch, so it works even when Holo holds focus and you cannot reach the terminal (on macOS it needs Input Monitoring permission). You can also press Ctrl+C in the launching terminal, or run holo stop from any other terminal; holo stop --force additionally kills the runtime. For host-launched runs, run holo stop or cancel the request from your MCP or ACP host. Bound risky tasks ahead of time with --max-steps or --max-time-s.

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 Use HoloDesktop CLI as an MCP server 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 Use HoloDesktop CLI as an ACP sub-agent for host 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.

​Commands

​Run

​Stop a run

​MCP

​ACP

​Install

​Login

​Whoami

​Doctor

Commands

Run

Stop a run

MCP

ACP

Install

Login

Whoami

Doctor