diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx index f481e7ba..6fbc20fd 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,65 @@ 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 + + + +## 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 +183,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 diff --git a/openhands/usage/run-openhands/headless-mode.mdx b/openhands/usage/run-openhands/headless-mode.mdx index cf0c4674..3792b360 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 +# 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 --exp --headless --file src/app.py --task "Add error handling to this file" + +# Run in headless mode with auto-approval +openhands --exp --headless --always-approve --task "Run tests and fix any failures" + +# Exit without confirmation prompts +openhands --exp --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: