hapi/cli

hapi CLI

Run Claude Code or Codex sessions from your terminal and control them remotely through the hapi server.

What it does

• Starts Claude Code sessions and registers them with hapi-server.
• Starts Codex mode for OpenAI-based sessions.
• Provides an MCP stdio bridge for external tools.
• Manages a background daemon for long-running sessions.
• Includes diagnostics and auth helpers.

Typical flow

1. Start the server and set env vars (see ../server/README.md).
2. Set the same CLI_API_TOKEN on this machine or run hapi auth login.
3. Run hapi to start a session.
4. Use the web app or Telegram Mini App to monitor and control.

Quickstart

# Point to the server if it is not on localhost:3006
export HAPI_BOT_URL="https://your-server-domain"

hapi              # prompts for CLI_API_TOKEN and saves it locally

Commands

• hapi - start a Claude Code session (passes through Claude CLI flags)
• hapi codex - start Codex mode
• hapi mcp - start MCP stdio bridge
• hapi auth - login/status/logout for CLI_API_TOKEN
• hapi server - start the bundled server (single binary workflow)
• hapi daemon - manage background service
• hapi doctor - diagnostics and cleanup

Configuration

Required:

• CLI_API_TOKEN - shared secret; must match the server
• HAPI_BOT_URL - server base URL (default: http://localhost:3006)

CLI_API_TOKEN can be set via env or stored in ~/.hapi/settings.json (env wins).

Optional:

• HAPI_HOME - config/data directory (default: ~/.hapi)
• HAPI_EXPERIMENTAL - enable experimental features (true/1/yes)
• HAPI_HTTP_MCP_URL - default MCP target for hapi mcp
• HAPI_CLAUDE_PATH - path to a specific claude executable
• HAPI_USE_BUNDLED_CLAUDE - set to 1 to prefer node_modules claude
• HAPI_USE_GLOBAL_CLAUDE - set to 1 to prefer global claude

Requirements

• Claude CLI installed and logged in (claude on PATH).
• Bun for building from source.

Build from source

From the repo root:

bun install
bun run build:cli
bun run build:cli:exe

For an all-in-one binary that also embeds the web app:

bun run build:single-exe

Related docs

• ../server/README.md
• ../web/README.md