CLI

The Command-Line Interface (CLI) provides a powerful interface that lets you engage with OpenHands directly from your terminal.

Overview

This mode is different from the headless mode, which is non-interactive and better for scripting.

If you’re upgrading from a CLI version before release 1.0.0, you’ll need to redo your settings setup as the configuration format has changed.

Getting Started

Using uv (recommended)

Requires Python 3.12+ and uv installed.

Install OpenHands:

uv tool install openhands --python 3.12

Run OpenHands:

openhands

Upgrade OpenHands:

uv tool upgrade openhands --python 3.12

Executable Binary

1. Download the executable binary from the OpenHands CLI release page and rename it to openhands for simplicity.

2. Make it executable:

chmod +x ./openhands

3. Run the executable:

./openhands

Your system may require you to allow permissions to run the executable.

MacOS

We are working on a fix for this issue.

When running the OpenHands CLI on Mac, you will get a warning that says “openhands can’t be opened because Apple cannot check it for malicious software.”

1. Open System Settings.

2. Go to Privacy & Security.

3. Scroll down to Security and click Allow Anyway.

4. Rerun the OpenHands CLI.

   

Using Docker

1. Set the following environment variable in your terminal:

   • SANDBOX_VOLUMES to specify the directory you want OpenHands to access (See using SANDBOX_VOLUMES for more info)

2. Ensure you have configured your settings before starting:

   • Set up ~/.openhands/settings.json with your LLM configuration

3. Run the following command:

docker run -it \
    --pull=always \
    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.openhands.dev/openhands/runtime:0.62-nikolaik \
    -e SANDBOX_USER_ID=$(id -u) \
    -e SANDBOX_VOLUMES=$SANDBOX_VOLUMES \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v ~/.openhands:/root/.openhands \
    --add-host host.docker.internal:host-gateway \
    --name openhands-cli-$(date +%Y%m%d%H%M%S) \
    python:3.12-slim \
    bash -c "pip install uv && uv tool install openhands --python 3.12 && openhands"

The -e SANDBOX_USER_ID=$(id -u) is passed to the Docker command to ensure the sandbox user matches the host user’s permissions. This prevents the agent from creating root-owned files in the mounted workspace.

The first time you run the CLI, it will take you through configuring the required LLM settings. These will be saved for future sessions.

The conversation history will be saved in ~/.openhands/conversations.

Interactive CLI Overview

What is CLI Mode?

CLI mode enables real-time interaction with OpenHands through the terminal. You can type natural language tasks, use interactive commands, and receive instant feedback—all inside your terminal.

CLI Options and Arguments

The OpenHands CLI supports various command-line options to customize your experience:

Basic Options

• --version or -v: Display the CLI version
• --task "your task": Start the CLI with an initial task message
• --file path/to/file: Start the CLI with a specific file context
• --headless: Run in headless mode with auto-exit functionality
• --exit-without-confirmation: Exit without confirmation prompts

Experimental UI

The experimental UI is available starting from CLI version 1.5.0 and provides an enhanced terminal experience.

Enable the experimental UI with the --exp flag:

openhands --exp

Experimental UI Features:

• Enhanced Visual Experience: Consistent dark mode CLI UI that overrides light-themed terminals
• Loading Indicators: Spinner animations for long-running commands
• Smart Queuing: Queue prompts while the agent is running to avoid interruptions
• File Search: Use the @ macro to search and reference files in your project
• Collapsible Messages: Reduced verbosity with optionally collapsible CLI messages
• Multi-line Support: Improved multi-line input handling with automatic paste detection

Approval and Confirmation Modes

Control how the CLI handles agent actions:

• --always-approve: Automatically approve all agent actions without prompting
• --llm-approve: Use the LLM to automatically approve actions based on context

Skills and Capabilities

The CLI automatically loads and provides access to:

• Project Skills: Custom skills defined in your project’s .openhands/skills/ directory
• User Skills: Personal skills from ~/.openhands/skills/
• Public Skills: Community-contributed skills from the OpenHands skills repository
• Legacy Microagents: Backward compatibility with existing microagent configurations

Version Management

The CLI includes automatic version checking and will prompt you when updates are available. You can check your current version with:

openhands --version

CLI Commands and Settings

The OpenHands CLI provides various commands for managing settings, conversations, and configurations. For detailed information about available commands, configuration options, and troubleshooting, see the CLI Settings page.

Key features include:

• Interactive settings configuration with /settings
• MCP server management with /mcp
• Conversation management with /new and /help
• Memory management with /condense
• Real-time status monitoring and control