README.md

April 15, 2026 · View on GitHub

OpenHands V1 CLI

(Powered by OpenHands Software Agent SDK)

Run OpenHands agent inside your terminal, favorite IDE, CI pipelines, local browser, or secure OpenHands Cloud sandboxes.

Installation

Using uv (Recommended)

Requires Python 3.12+ and uv 0.11.6 or newer.

uv tool install openhands --python 3.12

Executable Binary

Install the standalone binary with the install script:

curl -fsSL https://install.openhands.dev/install.sh | sh

Usage

Quick Start

The first time you run the CLI, it will guide you through configuring your LLM settings:

openhands

Configuration

OpenHands CLI stores configuration under ~/.openhands/ (created on first run):

agent_settings.json: persisted agent settings (including condenser config)
cli_config.json: CLI/TUI preferences (e.g., critic enabled)
mcp.json: MCP server configuration

By default, environment variables like LLM_API_KEY, LLM_MODEL, and LLM_BASE_URL are ignored; pass --override-with-envs to apply them (not persisted).

Running Modes

Mode	Command	Best For
Terminal (TUI)	`openhands`	Interactive development
IDE Integration	`openhands acp`	IDEs (Toad, Zed, VSCode, JetBrains, etc)
Headless	`openhands --headless -t "task"`	CI, scripts, and automation
Web Interface	`openhands web`	Browser-based TUI
GUI Server	`openhands serve`	Full web GUI

Features

MCP Servers

Extend OpenHands capabilities with Model Context Protocol (MCP) servers:

# List configured servers
openhands mcp list

# Add a server
openhands mcp add tavily --transport stdio \
  npx -- -y mcp-remote "https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>"

# Enable/disable servers
openhands mcp enable <server-name>
openhands mcp disable <server-name>

Confirmation Modes

Control how the agent handles actions:

# Default: ask for confirmation on each action
openhands

# Auto-approve all actions
openhands --always-approve  # or --yolo

# LLM-based security analyzer
openhands --llm-approve

Cloud Conversations

Run tasks on OpenHands Cloud. First, authenticate with OpenHands Cloud to fetch your settings:

# Login to OpenHands Cloud
openhands login

# Run a task on OpenHands Cloud
openhands cloud -t "Fix the login bug"

Headless Mode

Run OpenHands without the interactive UI for CI/CD pipelines and automation:

openhands --headless -t "Write unit tests for auth.py"
openhands --headless -f instructions.md  # or use a file

# With JSON output for parsing
openhands --headless --json -t "Create a Flask app"

Resume Conversations

openhands --resume              # list recent conversations
openhands --resume <id>         # resume specific conversation
openhands --resume --last       # resume most recent