What is the HAPI CLI?
The HAPI CLI is a command-line tool that wraps AI coding agents and connects them to the HAPI hub for remote control. It allows you to:- Start Claude Code sessions with remote control capabilities
- Run Codex mode for OpenAI-based sessions
- Use Cursor Agent for Cursor CLI sessions
- Start Gemini sessions via ACP (Anthropic Code Plugins)
- Run OpenCode sessions via ACP and plugin hooks
- Manage background runners for long-running sessions
- Control sessions remotely through web or mobile apps
Installation
Install HAPI CLI via npm:Requirements
Depending on which agent you want to use, you’ll need:- Claude Code: Claude CLI installed and logged in (
claudeon PATH) - Cursor Agent: Cursor Agent CLI (
agenton PATH)- macOS/Linux:
curl https://cursor.com/install -fsS | bash - Windows:
irm 'https://cursor.com/install?win32=true' | iex
- macOS/Linux:
- OpenCode: OpenCode CLI installed (
opencodeon PATH)
Basic Usage
Quick Start
- Start a session:
- If this is your first run, you’ll be prompted for your
CLI_API_TOKEN. You can also set it via environment variable:
- Use the web app or Telegram Mini App to monitor and control your session.
Command Structure
All HAPI commands follow this structure:Available Commands
Session Commands
Start and manage AI agent sessions (Claude, Codex, Cursor, Gemini, OpenCode)
Authentication
Manage CLI authentication and tokens
Runner Management
Control the background service that manages sessions
Hub Server
Start the bundled HAPI hub server
Diagnostics
System diagnostics and troubleshooting
Configuration
Environment variables and settings
Common Examples
Start a Claude session
Start with bypass permissions (YOLO mode)
Resume a previous session
Start Codex mode
Start Cursor Agent
Check authentication status
Run diagnostics
How It Works
- CLI wraps agent: The HAPI CLI spawns your chosen AI agent (Claude, Codex, Cursor, etc.)
- Connects to hub: Establishes a Socket.IO connection to the HAPI hub
- Registers session: Creates a session record and streams agent events to the hub
- Remote control: Web/mobile apps can send commands and receive updates in real-time
- Background runner: Optionally runs as a daemon to keep sessions alive
Next Steps
- Session Commands - Learn about all available session types
- Authentication - Set up your CLI token
- Environment Variables - Configure HAPI CLI
- Settings File - Customize local settings