> ## Documentation Index
> Fetch the complete documentation index at: https://hub.hcompany.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Common HoloDesktop CLI commands and options.

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`.

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
holo run \
  --model holo3-1-35b-a3b \
  "Open TextEdit and write a short note saying HoloDesktop CLI is installed"
```

Local mode:

```bash theme={null}
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

```bash theme={null}
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](/holo-desktop-cli/integrations/use-mcp) for host setup.

## ACP

```bash theme={null}
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](/holo-desktop-cli/integrations/use-acp) for host setup.

## Install

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
holo login --force
```

## Whoami

```bash theme={null}
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

```bash theme={null}
holo doctor
```

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