---
title: CLI Mode
description: CLI mode provides a powerful interactive Command-Line Interface (CLI) that lets you engage with OpenHands directly from your terminal.
---

This mode is different from the [headless mode](./headless-mode), which is non-interactive and better for scripting.

## Getting Started

### Running with Python

1. Ensure you have followed the [Development setup instructions](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md).
2. Set your model, API key, and other preferences using environment variables or with the [`config.toml`](https://github.com/All-Hands-AI/OpenHands/blob/main/config.template.toml) file.
3. Launch an interactive OpenHands conversation from the command line:

```bash
poetry run python -m openhands.cli.main
```

This command opens an interactive prompt where you can type tasks or commands and get responses from OpenHands.

### Running with Docker

1. Set the following environment variables in your terminal:
   - `SANDBOX_VOLUMES` to specify the directory you want OpenHands to access ([See using SANDBOX_VOLUMES for more info](../runtimes/docker#using-sandbox_volumes))
   - `LLM_MODEL` - the LLM model to use (e.g. `export LLM_MODEL="anthropic/claude-sonnet-4-20250514"`)
   - `LLM_API_KEY` - your API key (e.g. `export LLM_API_KEY="sk_test_12345"`)

2. Run the following command:

```bash
docker run -it \
    --pull=always \
    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.41-nikolaik \
    -e SANDBOX_USER_ID=$(id -u) \
    -e SANDBOX_VOLUMES=$SANDBOX_VOLUMES \
    -e LLM_API_KEY=$LLM_API_KEY \
    -e LLM_MODEL=$LLM_MODEL \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v ~/.openhands-state:/.openhands-state \
    --add-host host.docker.internal:host-gateway \
    --name openhands-app-$(date +%Y%m%d%H%M%S) \
    docker.all-hands.dev/all-hands-ai/openhands:0.41 \
    python -m openhands.cli.main --override-cli-mode true
```

This launches the CLI in Docker, allowing you to interact with OpenHands as described above.

The `-e SANDBOX_USER_ID=$(id -u)` ensures files created by the agent in your workspace have the correct permissions.

## Interactive CLI Overview

### What is CLI Mode?

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

### Starting a Conversation

When you start the CLI, you'll see a welcome message and a prompt (`>`). Enter your first task or type a command to
begin your conversation.

### Available Commands

You can use the following commands whenever the prompt (`>`) is displayed:

| Command      | Description                                                    |
|--------------|----------------------------------------------------------------|
| `/help`      | Show all available interactive commands and their descriptions |
| `/exit`      | Exit the application                                           |
| `/init`      | Initialize a new repository for agent exploration              |
| `/status`    | Show conversation details and usage metrics                    |
| `/new`       | Start a new conversation                                       |
| `/settings`  | View and modify current LLM/agent settings                     |
| `/resume`    | Resume the agent if paused                                     |

#### Settings and Configuration

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

- **Basic settings**: Choose a model/provider and enter your API key.
- **Advanced settings**: Set custom endpoints, enable or disable confirmation mode, and configure memory condensation.

Settings can also be managed via the `config.toml` file.

#### Repository Initialization

The `/init` command helps the agent understand your project by creating a `.openhands/microagents/repo.md` file with
project details and structure. Use this when onboarding the agent to a new codebase.

#### Agent Pause/Resume Feature

You can pause the agent while it is running by pressing `Ctrl-P`. To continue the conversation after pausing, simply
type `/resume` at the prompt.

## 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.
- For advanced LLM configuration, use the advanced options in `/settings`.
- When confirmation mode is enabled, the CLI will prompt before sensitive operations. You can type `a` or `always` at the first confirmation prompt to automatically confirm subsequent actions for the current conversation.
- If you want to start over, use `/new` to begin a fresh conversation without restarting the CLI.

---