Command Reference

Complete reference for all OpenHands CLI commands and options

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>

login

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

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:

{
  "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

See Also

• Installation - Install the CLI
• Quick Start - Get started
• MCP Servers - Configure MCP servers