From bb95577add978ac4f5dd5b049911de72f2d21289 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 16 Dec 2025 15:27:59 +0000 Subject: [PATCH 1/3] Update CLI documentation with new features since v1.2.0 - Add experimental UI documentation (--exp flag) with dark mode, spinners, file search - Document new CLI options: --task, --file, --version, --headless, --always-approve, --llm-approve - Add ACP integration documentation and enhanced slash commands - Document automatic skills loading (project, user, public skills) - Add /condense command for memory management - Update installation links to OpenHands-CLI repository - Enhance CLI settings page with approval modes and confirmation options Co-authored-by: openhands --- openhands/usage/run-openhands/cli-mode.mdx | 76 ++++++++++++++++++- .../usage/run-openhands/cli-settings.mdx | 37 ++++++++- 2 files changed, 109 insertions(+), 4 deletions(-) diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx index f481e7ba..9a1246c0 100644 --- a/openhands/usage/run-openhands/cli-mode.mdx +++ b/openhands/usage/run-openhands/cli-mode.mdx @@ -44,8 +44,8 @@ configuration format has changed. ``` - 1. Download the executable binary from - [OpenHands release page](https://github.com/OpenHands/OpenHands/releases/tag/1.0.1-cli) and rename it to + 1. Download the executable binary from the + [OpenHands CLI release page](https://github.com/OpenHands/OpenHands-CLI/releases/latest) and rename it to `openhands` for simplicity. 2. Make it executable: @@ -117,7 +117,76 @@ The conversation history will be saved in `~/.openhands/conversations`. 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 Commands and Settings +## 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: + +```bash +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 + +### Example Usage + +```bash +# Start with a specific task +openhands --task "Fix the bug in main.py" + +# Start with experimental UI and a file +openhands --exp --file src/app.py --task "Add error handling to this file" + +# Run in headless mode with auto-approval +openhands --headless --always-approve --task "Run tests and fix any failures" +``` + +## 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: + +```bash +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](/openhands/usage/run-openhands/cli-settings) page. @@ -125,4 +194,5 @@ 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 diff --git a/openhands/usage/run-openhands/cli-settings.mdx b/openhands/usage/run-openhands/cli-settings.mdx index b06e9ab5..92c145d1 100644 --- a/openhands/usage/run-openhands/cli-settings.mdx +++ b/openhands/usage/run-openhands/cli-settings.mdx @@ -8,7 +8,25 @@ description: Configuration and command reference for the OpenHands Command-Line 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 +### Core Commands + +- `/help` - Display all available commands and their descriptions +- `/new` - Start a new conversation without restarting the CLI +- `/settings` - Configure your model, API key, and other preferences +- `/mcp` - View MCP server status and configuration +- `/condense` - Force compact conversation history to save memory and tokens + +### ACP Integration Commands + + +ACP (Agent Computer Protocol) integration provides enhanced agent capabilities and is available starting from CLI version 1.3.0. + + +When ACP is enabled, additional slash commands become available for managing agent sessions and interactions. These commands provide advanced control over agent behavior and session management. + +## Settings and Configuration + +### Interactive Settings Configuration You can update your model, API key, and other preferences using the `/settings` command. Just follow the prompts: @@ -17,6 +35,23 @@ follow the prompts: - **Advanced settings**: Set custom models and toggle [memory condensation](/openhands/usage/settings/llm-settings#memory-condensation). +### Memory Management + +The `/condense` command allows you to manually trigger conversation history condensation: + +- **Purpose**: Reduces token usage by compacting conversation history +- **When to use**: When conversations become long or you want to optimize performance +- **Effect**: Preserves important context while reducing overall message count + +### Confirmation and Approval Modes + +The CLI supports different modes for handling agent actions: + +- **Interactive Mode** (default): Prompts for approval before executing actions +- **Always Approve Mode** (`--always-approve`): Automatically approves all actions +- **LLM Approve Mode** (`--llm-approve`): Uses the LLM to intelligently approve actions +- **Confirmation Mode**: Enhanced approval system with detailed action previews + ### MCP Server Management From 013a28941da0ff210b001de67bcea4f0fbe77e9e Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 16 Dec 2025 17:01:19 +0000 Subject: [PATCH 2/3] Move Example Usage section from CLI to Headless page - Moved Example Usage section from CLI page to Headless page - Created 'With CLI' as the first section on Headless page - Added --headless flag to all examples in the moved section - Added additional CLI headless options documentation Co-authored-by: openhands --- openhands/usage/run-openhands/cli-mode.mdx | 11 ------- .../usage/run-openhands/headless-mode.mdx | 31 +++++++++++++++++++ 2 files changed, 31 insertions(+), 11 deletions(-) diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx index 9a1246c0..6fbc20fd 100644 --- a/openhands/usage/run-openhands/cli-mode.mdx +++ b/openhands/usage/run-openhands/cli-mode.mdx @@ -156,18 +156,7 @@ 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 -### Example Usage -```bash -# Start with a specific task -openhands --task "Fix the bug in main.py" - -# Start with experimental UI and a file -openhands --exp --file src/app.py --task "Add error handling to this file" - -# Run in headless mode with auto-approval -openhands --headless --always-approve --task "Run tests and fix any failures" -``` ## Skills and Capabilities diff --git a/openhands/usage/run-openhands/headless-mode.mdx b/openhands/usage/run-openhands/headless-mode.mdx index cf0c4674..419df29d 100644 --- a/openhands/usage/run-openhands/headless-mode.mdx +++ b/openhands/usage/run-openhands/headless-mode.mdx @@ -6,6 +6,37 @@ description: You can run OpenHands with a single command, without starting the w This is different from [the CLI](/openhands/usage/run-openhands/cli-mode), which is interactive, and better for active development. +## With CLI + +The OpenHands CLI supports headless mode through the `--headless` flag, which enables non-interactive execution with automatic exit functionality. This is perfect for scripting and automation scenarios. + +### Example Usage + +```bash +# Start with a specific task in headless mode +openhands --headless --task "Fix the bug in main.py" + +# Run with experimental UI and a file in headless mode +openhands --headless --exp --file src/app.py --task "Add error handling to this file" + +# Run in headless mode with auto-approval +openhands --headless --always-approve --task "Run tests and fix any failures" + +# Exit without confirmation prompts +openhands --headless --exit-without-confirmation --task "Generate documentation for the project" +``` + +### CLI Headless Options + +When using the CLI in headless mode, you can combine the `--headless` flag with other CLI options: + +- `--task "your task"`: Start with an initial task message +- `--file path/to/file`: Start with a specific file context +- `--always-approve`: Automatically approve all agent actions +- `--llm-approve`: Use the LLM to automatically approve actions +- `--exit-without-confirmation`: Exit without confirmation prompts +- `--exp`: Enable experimental UI features + ## With Python To run OpenHands in headless mode with Python: From ab6aa9c9b91db101e91d95365e553188a2ce0de8 Mon Sep 17 00:00:00 2001 From: jpelletier1 <44589723+jpelletier1@users.noreply.github.com> Date: Tue, 16 Dec 2025 13:53:37 -0500 Subject: [PATCH 3/3] Update headless-mode.mdx --- openhands/usage/run-openhands/headless-mode.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/openhands/usage/run-openhands/headless-mode.mdx b/openhands/usage/run-openhands/headless-mode.mdx index 419df29d..3792b360 100644 --- a/openhands/usage/run-openhands/headless-mode.mdx +++ b/openhands/usage/run-openhands/headless-mode.mdx @@ -13,17 +13,17 @@ The OpenHands CLI supports headless mode through the `--headless` flag, which en ### Example Usage ```bash -# Start with a specific task in headless mode +# Launch a specific task into the terminal UI from headless mode openhands --headless --task "Fix the bug in main.py" # Run with experimental UI and a file in headless mode -openhands --headless --exp --file src/app.py --task "Add error handling to this file" +openhands --exp --headless --file src/app.py --task "Add error handling to this file" # Run in headless mode with auto-approval -openhands --headless --always-approve --task "Run tests and fix any failures" +openhands --exp --headless --always-approve --task "Run tests and fix any failures" # Exit without confirmation prompts -openhands --headless --exit-without-confirmation --task "Generate documentation for the project" +openhands --exp --headless --exit-without-confirmation --task "Generate documentation for the project" ``` ### CLI Headless Options