Skip to content

🙌 OpenHands: AI-Driven Development

refactor: Update CLI mode documentation with commands and interactive features (#8303)

Bashwara Undupitiya56651bb93c57
diff --git a/docs/modules/usage/how-to/cli-mode.md b/docs/modules/usage/how-to/cli-mode.md
index 8bc12dda37..65605312f0 100644
--- a/docs/modules/usage/how-to/cli-mode.md
+++ b/docs/modules/usage/how-to/cli-mode.md
@@ -1,38 +1,37 @@
# CLI Mode
-OpenHands can be run in an interactive CLI mode, which allows users to start an interactive session via the command line.
+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.
-## With Python
+## Getting Started
-To start an interactive OpenHands session via the command line:
+### Prerequisites
+- Ensure you have followed the [Development setup instructions](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md).
+- You will need your LLM model name and API key.
-1. Ensure you have followed the [Development setup instructions](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md).
-2. Run the following command:
+### Running with Python
+To launch an interactive OpenHands conversation from the command line:
```bash
-poetry run python -m openhands.core.cli
+poetry run python -m openhands.cli.main
```
-This command will start an interactive session where you can input tasks and receive responses from OpenHands.
-
-You'll need to be sure to set your model, API key, and other settings via environment variables
-[or the `config.toml` file](https://github.com/All-Hands-AI/OpenHands/blob/main/config.template.toml).
+This command opens an interactive prompt where you can type tasks or commands and get responses from OpenHands.
-## With Docker
+You can 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.
-To run OpenHands in CLI mode with Docker:
+### Running with Docker
+To use OpenHands CLI mode with Docker:
-1. Set the following environmental variables in your terminal:
+1. Set the following environment variables in your terminal:
+ - `SANDBOX_VOLUMES` to specify the directory you want OpenHands to access (Ex: `export SANDBOX_VOLUMES=$(pwd)/workspace:/workspace:rw`).
+ - The agent works in `/workspace` by default, so mount your project directory there if you want the agent to modify files.
+ - For read-only data, use a different mount path (Ex: `export SANDBOX_VOLUMES=$(pwd)/workspace:/workspace:rw,/path/to/large/dataset:/data:ro`).
+ - `LLM_MODEL` — the LLM model to use (e.g. `export LLM_MODEL="anthropic/claude-3-5-sonnet-20241022"`)
+ - `LLM_API_KEY` — your API key (e.g. `export LLM_API_KEY="sk_test_12345"`)
-- `SANDBOX_VOLUMES` to specify the directory you want OpenHands to access (Ex: `export SANDBOX_VOLUMES=$(pwd)/workspace:/workspace:rw`).
- - The agent works in `/workspace` by default, so mount your project directory there if you want the agent to modify files.
- - For read-only data, use a different mount path (Ex: `export SANDBOX_VOLUMES=$(pwd)/workspace:/workspace:rw,/path/to/large/dataset:/data:ro`).
-- `LLM_MODEL` to the model to use (Ex: `export LLM_MODEL="anthropic/claude-3-5-sonnet-20241022"`).
-- `LLM_API_KEY` to the API key (Ex: `export LLM_API_KEY="sk_test_12345"`).
-
-2. Run the following Docker command:
+2. Run the following command:
```bash
docker run -it \
@@ -47,10 +46,73 @@ docker run -it \
--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.37 \
- python -m openhands.core.cli
+ python -m openhands.cli.main
```
-This command will start an interactive session in Docker where you can input tasks and receive responses from OpenHands.
+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.
+
+### Entering Tasks
+Type your request (for example, "Refactor the utils.py file to improve readability") and press Enter. The agent will process your input and reply.
+
+---
+
+## 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.
-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.
+---