How openhands/openhands-cli works
OpenHands V1 CLI is a terminal and IDE-facing interface for running coding-agent conversations, with headless, browser/web, GUI-server, and OpenHands Cloud modes. The primary workflow starts at the CLI entry point, accepts a task, runs or resumes an agent conversation, and presents or persists its progress. TUI conversation management, confirmation and critic refinement form a distinct internal layer; authentication, MCP configuration, and cloud conversations are additional capabilities. Some mode implementations are unsampled, so their nodes are retained from the README and tree without guessed internal links.
Main entry points: entrypoint.py CLI entry point · conversation_manager.py Conversation manager · state.py Conversation state · locations.py Persistence locations
Components 23
CLI entry and modes
- CLI entry point
openhands_cli/entrypoint.py - Terminal UI
openhands_cli/tui/textual_app.py - Web mode
openhands_cli/argparsers/web_parser.py - GUI server
openhands_cli/gui_launcher.py - Headless mode
openhands_cli/argparsers/main_parser.py
TUI conversations
- Conversation manager
openhands_cli/tui/core/conversation_manager.py - Conversation state
openhands_cli/tui/core/state.py - Runner registry
openhands_cli/tui/core/runner_registry.py - Conversation runner
openhands_cli/tui/core/conversation_runner.py - Switch controller
openhands_cli/tui/core/conversation_switch_controller.py - Critic refinement
openhands_cli/tui/core/refinement_controller.py - Local conversations
openhands_cli/conversations/store/local.py
Agent interfaces
- IDE ACP agent
openhands_cli/acp_impl/agent/base_agent.py
Accounts and cloud
- Cloud authentication
openhands_cli/auth/login_command.py - Cloud API client
openhands_cli/auth/api_client.py - Token storage
openhands_cli/auth/token_storage.py - Cloud conversations
openhands_cli/cloud/conversation.py
Settings and integrations
- MCP management
openhands_cli/mcp/mcp_commands.py - MCP configuration
openhands_cli/mcp/mcp_utils.py - Agent settings
openhands_cli/stores/agent_store.py - CLI preferences
openhands_cli/stores/cli_settings.py - Persistence locations
openhands_cli/locations.py
Other components
- CLI user
Connections 28
- CLI user → CLI entry point: starts
README.md - CLI entry point → Terminal UI: launches
openhands_cli/entrypoint.py - CLI entry point → IDE ACP agent: dispatches
openhands_cli/entrypoint.py - CLI entry point → Headless mode: dispatches
openhands_cli/argparsers/main_parser.py - CLI entry point → Web mode: dispatches
openhands_cli/entrypoint.py - CLI entry point → GUI server: dispatches
openhands_cli/entrypoint.py - CLI entry point → Cloud authentication: dispatches
openhands_cli/entrypoint.py - CLI entry point → Cloud conversations: dispatches
openhands_cli/entrypoint.py - CLI entry point → MCP management: dispatches
openhands_cli/entrypoint.py - Conversation manager → Runner registry: delegates to
openhands_cli/tui/core/conversation_manager.py - Conversation manager → Switch controller: delegates to
openhands_cli/tui/core/conversation_manager.py - Conversation manager → Critic refinement: delegates to
openhands_cli/tui/core/conversation_manager.py - Conversation manager → Conversation state: updates
openhands_cli/tui/core/conversation_manager.py - Runner registry → Conversation runner: creates
openhands_cli/tui/core/runner_registry.py - Switch controller → Runner registry: selects runner
openhands_cli/tui/core/conversation_switch_controller.py - Switch controller → Conversation state: updates
openhands_cli/tui/core/conversation_switch_controller.py - Critic refinement → Conversation state: reads settings
openhands_cli/tui/core/refinement_controller.py - Conversation runner → Conversation state: uses state
openhands_cli/tui/core/conversation_runner.py - Conversation manager → Local conversations: manages conversations
- Cloud authentication → Cloud API client: calls
openhands_cli/auth/login_command.py - Cloud authentication → Token storage: stores credentials
openhands_cli/auth/login_command.py - Cloud conversations → Cloud API client: uses client
openhands_cli/cloud/conversation.py - MCP management → MCP configuration: uses configuration
openhands_cli/mcp/mcp_commands.py - Agent settings → MCP configuration: reads configuration
openhands_cli/stores/agent_store.py - Agent settings → Persistence locations: resolves storage
openhands_cli/stores/agent_store.py - Token storage → Persistence locations: resolves storage
openhands_cli/auth/token_storage.py - Local conversations → Persistence locations: resolves storage
openhands_cli/conversations/store/local.py - CLI preferences → Persistence locations: resolves storage