CLI Commands Reference

Complete reference for Happy Coder command-line interface.

Installation

npm install -g happy-coder

Requirements:

• Node.js 18 or later
• Claude Code CLI installed

Basic Commands

Start Happy Coder

happy

Starts the Happy Coder daemon, connecting your terminal session to the mobile app.

Device Pairing

happy --auth

Displays QR code for pairing with mobile device.

Options:

Flag	Description
--qr-size large	Display larger QR code
--no-qr	Show manual entry code instead

Version Information

happy --version

Help

happy --help

Configuration Options

Custom Server URL

export HAPPY_SERVER_URL="https://your-server.com"
happy

Custom Session Name

HAPPY_SESSION_NAME="frontend-project" happy

Custom Port

happy --port 8766

Push Notifications

Test Notifications

happy notify -p "message content" -t "Notification Title"

Flag	Description
-p	Message content
-t	Notification title

Claude Code Integration

Happy Coder wraps Claude Code. All Claude Code commands work:

Plan Mode

# In Happy session
/plan Add dark mode toggle

Custom Agents

# In Happy session
/bedtime
/review
/your-custom-agent

Slash Commands

All Claude Code slash commands are supported:

• /init - Initialize project
• /plan - Enter planning mode
• /agents - List available agents
• /help - Show help

Session Management

List Active Sessions

Sessions are managed through the mobile app. Each running happy instance appears as a session.

Multiple Sessions

Run multiple sessions on different machines or different directories:

# Terminal 1
cd ~/frontend && happy

# Terminal 2
cd ~/backend && happy

# Terminal 3 (SSH to VPS)
ssh vps "cd ~/project && happy"

Environment Variables

Variable	Default	Description
HAPPY_SERVER_URL	(Slopus server)	Relay server URL
HAPPY_SESSION_NAME	(hostname)	Session identifier
HAPPY_DEBUG	false	Enable debug logging

Self-Hosting Commands

Clone Server

git clone https://github.com/slopus/happy-server
cd happy-server

Build Docker Image

docker build -t happy-server:latest .

Run Server

docker run -d \
  --name happy-server \
  -p 3000:3000 \
  -e DATABASE_URL="postgresql://..." \
  -e REDIS_URL="redis://..." \
  -e SEED="your-seed" \
  happy-server:latest

Check Server Health

curl http://localhost:3000/health

Troubleshooting Commands

Check Node.js Version

node --version
# Should be v18.0.0 or higher

Check Claude Code Installation

claude --version

Find Process Using Port

# Linux/macOS
lsof -i :8765

# Windows
netstat -ano | findstr :8765

Kill Process

# Linux/macOS
kill -9 <PID>

# Windows
taskkill /F /PID <PID>

Common Workflows

Morning Start

cd ~/project
happy

Parallel Development

# Set up worktrees first
git worktree add ../experiment-1 -b experiment-1
git worktree add ../experiment-2 -b experiment-2

# Run in separate terminals
cd ../experiment-1 && HAPPY_SESSION_NAME="exp-1" happy
cd ../experiment-2 && HAPPY_SESSION_NAME="exp-2" happy

Self-Host Setup

# Configure client
export HAPPY_SERVER_URL="https://my-server.com"
happy --auth

Exit Codes

Code	Meaning
0	Success
1	General error
2	Invalid arguments
127	Command not found