Skip to main content

​
Basic Usage

openhands [OPTIONS] [COMMAND]

​
Global Options

OptionDescription
-v, --versionShow version number and exit
-t, --task TEXTInitial task to seed the conversation
-f, --file PATHPath to a file whose contents seed the conversation
--resume [ID]Resume a conversation. If no ID provided, lists recent conversations
--lastResume the most recent conversation (use with --resume)
--expUse textual-based UI (now default, kept for compatibility)
--headlessRun in headless mode (no UI, requires --task or --file)
--jsonEnable JSONL output (requires --headless)
--always-approveAuto-approve all actions without confirmation
--llm-approveUse LLM-based security analyzer for action approval
--exit-without-confirmationExit without showing confirmation dialog

​
Subcommands

​
serve

Launch the OpenHands GUI server using Docker. 
openhands serve [OPTIONS]
OptionDescription
--mount-cwdMount the current working directory into the container
--gpuEnable 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]
OptionDefaultDescription
--host0.0.0.0Host to bind the web server to
--port12000Port to bind the web server to
--debugfalseEnable 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]
OptionDescription
-t, --task TEXTInitial task to seed the conversation
-f, --file PATHPath to a file whose contents seed the conversation
--server-url URLOpenHands 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]
OptionDescription
--resume [ID]Resume a conversation by ID
--lastResume the most recent conversation
--always-approveAuto-approve all actions
--llm-approveUse LLM-based security analyzer
--streamingEnable 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...]
OptionDescription
--transportTransport type: http, sse, or stdio (required)
--headerHTTP header for http/sse (format: "Key: Value", repeatable)
--envEnvironment variable for stdio (format: KEY=value, repeatable)
--authAuthentication method (e.g., oauth)
--enabledEnable immediately (default)
--disabledAdd 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]
OptionDescription
--server-url URLOpenHands 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]
OptionDescription
--server-url URLServer 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 /):
CommandDescription
/settingsOpen the settings configuration menu
/newStart a new conversation
/helpShow all available commands
/mcpView MCP server status

​
Environment Variables

VariableDescription
LLM_API_KEYAPI key for your LLM provider
LLM_MODELModel to use
OPENHANDS_CLOUD_URLDefault cloud server URL
OPENHANDS_VERSIONDocker image version for openhands serve

​
Exit Codes

CodeMeaning
0Success
1Error or task failed
2Invalid arguments

​
Configuration Files

FilePurpose
~/.openhands/settings.jsonLLM and general settings
~/.openhands/mcp.jsonMCP server configurations
~/.openhands/conversations/Conversation history

​
See Also