openhands 1.12.1

OpenHands CLI - Terminal User Interface for OpenHands AI Agent

OpenHands V1 CLI

(Powered by OpenHands Software Agent SDK)

Deutsch | Español | français | 日本語 | 한국어 | Português | Русский | 中文

---

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.

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

Documentation

For complete documentation, visit https://docs.openhands.dev/openhands/usage/cli.

License

MIT License - see LICENSE for details.