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

# Command Reference

> Complete reference for all OpenHands CLI commands and options

## Basic Usage

```bash theme={null}
openhands [OPTIONS] [COMMAND]
```

## Global Options

| Option                        | Description                                                                                          |
| ----------------------------- | ---------------------------------------------------------------------------------------------------- |
| `-v, --version`               | Show version number and exit                                                                         |
| `-t, --task TEXT`             | Initial task to seed the conversation                                                                |
| `-f, --file PATH`             | Path to a file whose contents seed the conversation                                                  |
| `--resume [ID]`               | Resume a conversation. If no ID provided, lists recent conversations                                 |
| `--last`                      | Resume the most recent conversation (use with `--resume`)                                            |
| `--exp`                       | Use textual-based UI (now default, kept for compatibility)                                           |
| `--headless`                  | Run in headless mode (no UI, requires `--task` or `--file`)                                          |
| `--json`                      | Enable JSONL output (requires `--headless`)                                                          |
| `--always-approve`            | Auto-approve all actions without confirmation                                                        |
| `--llm-approve`               | Use LLM-based security analyzer for action approval                                                  |
| `--override-with-envs`        | Apply environment variables (`LLM_API_KEY`, `LLM_MODEL`, `LLM_BASE_URL`) to override stored settings |
| `--exit-without-confirmation` | Exit without showing confirmation dialog                                                             |

## Subcommands

### serve

Launch the OpenHands GUI server using Docker.

```bash theme={null}
openhands serve [OPTIONS]
```

| Option        | Description                                            |
| ------------- | ------------------------------------------------------ |
| `--mount-cwd` | Mount the current working directory into the container |
| `--gpu`       | Enable GPU support via nvidia-docker                   |

**Examples:**

```bash theme={null}
openhands serve
openhands serve --mount-cwd
openhands serve --gpu
openhands serve --mount-cwd --gpu
```

### web

Launch the CLI as a web application accessible via browser.

```bash theme={null}
openhands web [OPTIONS]
```

| Option    | Default   | Description                    |
| --------- | --------- | ------------------------------ |
| `--host`  | `0.0.0.0` | Host to bind the web server to |
| `--port`  | `12000`   | Port to bind the web server to |
| `--debug` | `false`   | Enable debug mode              |

**Examples:**

```bash theme={null}
openhands web
openhands web --port 8080
openhands web --host 127.0.0.1 --port 3000
openhands web --debug
```

### cloud

Create a new conversation in OpenHands Cloud.

```bash theme={null}
openhands cloud [OPTIONS]
```

| Option             | Description                                                                            |
| ------------------ | -------------------------------------------------------------------------------------- |
| `-t, --task TEXT`  | Initial task to seed the conversation                                                  |
| `-f, --file PATH`  | Path to a file whose contents seed the conversation                                    |
| `--server-url URL` | OpenHands server URL (default: [https://app.all-hands.dev](https://app.all-hands.dev)) |

**Examples:**

```bash theme={null}
openhands cloud -t "Fix the bug"
openhands cloud -f task.txt
openhands cloud --server-url https://custom.server.com -t "Task"
```

### acp

Start the Agent Client Protocol server for IDE integrations.

```bash theme={null}
openhands acp [OPTIONS]
```

| Option             | Description                         |
| ------------------ | ----------------------------------- |
| `--resume [ID]`    | Resume a conversation by ID         |
| `--last`           | Resume the most recent conversation |
| `--always-approve` | Auto-approve all actions            |
| `--llm-approve`    | Use LLM-based security analyzer     |
| `--streaming`      | Enable token-by-token streaming     |

**Examples:**

```bash theme={null}
openhands acp
openhands acp --llm-approve
openhands acp --resume abc123def456
openhands acp --resume --last
```

### mcp

Manage Model Context Protocol server configurations.

```bash theme={null}
openhands mcp <command> [OPTIONS]
```

#### mcp add

Add a new MCP server.

```bash theme={null}
openhands mcp add <name> --transport <type> [OPTIONS] <target> [-- args...]
```

| Option        | Description                                                      |
| ------------- | ---------------------------------------------------------------- |
| `--transport` | Transport type: `http`, `sse`, or `stdio` (required)             |
| `--header`    | HTTP header for http/sse (format: `"Key: Value"`, repeatable)    |
| `--env`       | Environment variable for stdio (format: `KEY=value`, repeatable) |
| `--auth`      | Authentication method (e.g., `oauth`)                            |
| `--enabled`   | Enable immediately (default)                                     |
| `--disabled`  | Add in disabled state                                            |

**Examples:**

```bash theme={null}
openhands mcp add my-api --transport http https://api.example.com/mcp
openhands mcp add my-api --transport http --header "Authorization: Bearer token" https://api.example.com
openhands mcp add local --transport stdio python -- -m my_server
openhands mcp add local --transport stdio --env "API_KEY=secret" python -- -m server
```

#### mcp list

List all configured MCP servers.

```bash theme={null}
openhands mcp list
```

#### mcp get

Get details for a specific MCP server.

```bash theme={null}
openhands mcp get <name>
```

#### mcp remove

Remove an MCP server configuration.

```bash theme={null}
openhands mcp remove <name>
```

#### mcp enable

Enable an MCP server.

```bash theme={null}
openhands mcp enable <name>
```

#### mcp disable

Disable an MCP server.

```bash theme={null}
openhands mcp disable <name>
```

### login

Authenticate with OpenHands Cloud.

```bash theme={null}
openhands login [OPTIONS]
```

| Option             | Description                                                                            |
| ------------------ | -------------------------------------------------------------------------------------- |
| `--server-url URL` | OpenHands server URL (default: [https://app.all-hands.dev](https://app.all-hands.dev)) |

**Examples:**

```bash theme={null}
openhands login
openhands login --server-url https://enterprise.openhands.dev
```

### logout

Log out from OpenHands Cloud.

```bash theme={null}
openhands logout [OPTIONS]
```

| Option             | Description                                                      |
| ------------------ | ---------------------------------------------------------------- |
| `--server-url URL` | Server URL to log out from (if not specified, logs out from all) |

**Examples:**

```bash theme={null}
openhands logout
openhands logout --server-url https://app.all-hands.dev
```

## Interactive Commands

Commands available inside the CLI (prefix with `/`):

| Command     | Description                         |
| ----------- | ----------------------------------- |
| `/help`     | Display available commands          |
| `/new`      | Start a new conversation            |
| `/history`  | Toggle conversation history         |
| `/confirm`  | Configure confirmation settings     |
| `/condense` | Condense conversation history       |
| `/skills`   | View loaded skills, hooks, and MCPs |
| `/feedback` | Send anonymous feedback about CLI   |
| `/exit`     | Exit the application                |

## Command Palette

Press `Ctrl+P` (or `Ctrl+\`) to open the command palette for quick access to:

| Option         | Description                                       |
| -------------- | ------------------------------------------------- |
| **History**    | Toggle conversation history panel                 |
| **Keys**       | Show keyboard shortcuts                           |
| **MCP**        | View MCP server configurations                    |
| **Maximize**   | Maximize/restore window                           |
| **Plan**       | View agent plan                                   |
| **Quit**       | Quit the application                              |
| **Screenshot** | Take a screenshot                                 |
| **Settings**   | Configure LLM model, API keys, and other settings |
| **Theme**      | Toggle color theme                                |

## Changing Your Model

### Via Settings UI

1. Press `Ctrl+P` to open the command palette
2. Select **Settings**
3. Choose your LLM provider and model
4. Save changes (no restart required)

### Via Configuration File

Edit `~/.openhands/agent_settings.json` and change the `model` field:

```json theme={null}
{
  "llm": {
    "model": "claude-sonnet-4-5-20250929",
    "api_key": "...",
    "base_url": "..."
  }
}
```

### Via Environment Variables

Temporarily override your model without changing saved configuration:

```bash theme={null}
export LLM_MODEL="gpt-4o"
export LLM_API_KEY="your-api-key"
openhands --override-with-envs
```

Changes made with `--override-with-envs` are not persisted.

## Environment Variables

| Variable              | Description                                           |
| --------------------- | ----------------------------------------------------- |
| `LLM_API_KEY`         | API key for your LLM provider                         |
| `LLM_MODEL`           | Model to use (requires `--override-with-envs`)        |
| `LLM_BASE_URL`        | Custom LLM base URL (requires `--override-with-envs`) |
| `OPENHANDS_CLOUD_URL` | Default cloud server URL                              |
| `OPENHANDS_VERSION`   | Docker image version for `openhands serve`            |

## Exit Codes

| Code | Meaning              |
| ---- | -------------------- |
| `0`  | Success              |
| `1`  | Error or task failed |
| `2`  | Invalid arguments    |

## Configuration Files

| File                               | Purpose                                |
| ---------------------------------- | -------------------------------------- |
| `~/.openhands/agent_settings.json` | LLM configuration and agent settings   |
| `~/.openhands/cli_config.json`     | CLI preferences (e.g., critic enabled) |
| `~/.openhands/mcp.json`            | MCP server configurations              |
| `~/.openhands/conversations/`      | Conversation history                   |

## See Also

* [Installation](/openhands/usage/cli/installation) - Install the CLI
* [Quick Start](/openhands/usage/cli/quick-start) - Get started
* [MCP Servers](/openhands/usage/cli/mcp-servers) - Configure MCP servers