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.

uvx --python 3.12 openhands

Create shell aliases for easy access across environments

Add the following to your shell configuration file (.bashrc, .zshrc, etc.):

alias openhands="uvx --python 3.12 openhands"
alias oh="uvx --python 3.12 openhands"

After adding these lines, reload your shell configuration with source ~/.bashrc or source ~/.zshrc (depending on your shell).

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.

Available Commands

The OpenHands CLI provides commands to help with settings and conversations. These commands work by typing / followed by the command. To see a list of all the available commands run /help when running the CLI.

Settings and Configuration

You can update your model, API key, and other preferences using the /settings command. Just follow the prompts:

• Basic settings: Choose a provider/model and enter your API key.
• Advanced settings: Set custom models and toggle memory condensation.

MCP Server Management

If you’re upgrading from a version before release 1.0.0, you’ll need to redo your MCP server configuration as the format has changed from TOML to JSON.

To configure Model Context Protocol (MCP) servers, you need to manually create and configure the ~/.openhands/mcp.json file using this configuration format.

The /mcp command in the CLI provides a read-only view of MCP server status:

• View active servers: Shows which MCP servers are currently active in the conversation.
• View pending changes: If the mcp.json file has been modified, shows which servers will be mounted when the conversation is restarted.

Tips and Troubleshooting

• Use /help at any time to see the list of available commands.
• If you encounter permission issues, make sure your workspace directory is trusted and all required environment variables are set correctly.
• If you want to start over, use /new to begin a fresh conversation without restarting the CLI.