https://github.com/openhands/openhands-cli
Lightweight OpenHands CLI in a binary executable
https://github.com/openhands/openhands-cli
Last synced: 2 months ago
JSON representation
Lightweight OpenHands CLI in a binary executable
- Host: GitHub
- URL: https://github.com/openhands/openhands-cli
- Owner: OpenHands
- License: mit
- Created: 2025-09-02T20:50:27.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-04-22T11:53:45.000Z (2 months ago)
- Last Synced: 2026-04-22T13:29:16.451Z (2 months ago)
- Language: Python
- Homepage: https://docs.openhands.dev/openhands/usage/cli/installation
- Size: 3.76 MB
- Stars: 160
- Watchers: 5
- Forks: 75
- Open Issues: 120
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
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](https://docs.astral.sh/uv/) 0.11.6 or newer.
```bash
uv tool install openhands --python 3.12
```
### Executable Binary
Install the standalone binary with the install script:
```bash
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:
```bash
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)](https://docs.openhands.dev/openhands/usage/cli/terminal) | `openhands` | Interactive development |
| [IDE Integration](https://docs.openhands.dev/openhands/usage/cli/ide/overview) | `openhands acp` | IDEs (Toad, Zed, VSCode, JetBrains, etc) |
| [Headless](https://docs.openhands.dev/openhands/usage/cli/headless) | `openhands --headless -t "task"` | CI, scripts, and automation |
| [Web Interface](https://docs.openhands.dev/openhands/usage/cli/web-interface) | `openhands web` | Browser-based TUI |
| [GUI Server](https://docs.openhands.dev/openhands/usage/cli/gui-server) | `openhands serve` | [Full web GUI](https://github.com/OpenHands/OpenHands)|
## Features
### [MCP Servers](https://docs.openhands.dev/openhands/usage/cli/mcp-servers)
Extend OpenHands capabilities with [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers:
```bash
# 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="
# Enable/disable servers
openhands mcp enable
openhands mcp disable
```
### [Confirmation Modes](https://docs.openhands.dev/openhands/usage/cli/command-reference)
Control how the agent handles actions:
```bash
# 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](https://docs.openhands.dev/openhands/usage/cli/cloud)
Run tasks on OpenHands Cloud. First, authenticate with OpenHands Cloud to fetch your settings:
```bash
# Login to OpenHands Cloud
openhands login
# Run a task on OpenHands Cloud
openhands cloud -t "Fix the login bug"
```
### [Headless Mode](https://docs.openhands.dev/openhands/usage/cli/headless)
Run OpenHands without the interactive UI for CI/CD pipelines and automation:
```bash
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
```bash
openhands --resume # list recent conversations
openhands --resume # 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](LICENSE) for details.
### Thank You to Our Contributors
### Trusted by Engineers at
