Command Reference - OpenHands Docs

Basic Usage

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.

openhands serve [OPTIONS]

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

Examples:

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.

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:

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.

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)

Examples:

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.

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:

openhands acp
openhands acp --llm-approve
openhands acp --resume abc123def456
openhands acp --resume --last

mcp

Manage Model Context Protocol server configurations.

openhands mcp <command> [OPTIONS]

mcp add

Add a new MCP server.

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:

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.

openhands mcp list

mcp get

Get details for a specific MCP server.

openhands mcp get <name>

mcp remove

Remove an MCP server configuration.

openhands mcp remove <name>

mcp enable

Enable an MCP server.

openhands mcp enable <name>

mcp disable

Disable an MCP server.

openhands mcp disable <name>

Authenticate with OpenHands Cloud.

openhands login [OPTIONS]

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

Examples:

openhands login
openhands login --server-url https://enterprise.openhands.dev

logout

Log out from OpenHands Cloud.

openhands logout [OPTIONS]

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

Examples:

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

Press Ctrl+P to open the command palette
Select Settings
Choose your LLM provider and model
Save changes (no restart required)

Via Configuration File

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

{
  "llm": {
    "model": "claude-sonnet-4-5-20250929",
    "api_key": "...",
    "base_url": "..."
  }
}

Via Environment Variables

Temporarily override your model without changing saved configuration:

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

​Basic Usage

​Global Options

​Subcommands

​serve

​web

​cloud

​acp

​mcp

​mcp add

​mcp list

​mcp get

​mcp remove

​mcp enable

​mcp disable

​login

​logout

​Interactive Commands

​Command Palette

​Changing Your Model

​Via Settings UI

​Via Configuration File

​Via Environment Variables

​Environment Variables

​Exit Codes

​Configuration Files

​See Also

Basic Usage

Global Options

Subcommands

serve

web

cloud

acp

mcp

mcp add

mcp list

mcp get

mcp remove

mcp enable

mcp disable

login

logout

Interactive Commands

Command Palette

Changing Your Model

Via Settings UI

Via Configuration File

Via Environment Variables

Environment Variables

Exit Codes

Configuration Files

See Also