CLI Reference

happy [options] [-- claude-code-args]

happy

# Basic start
happy
 
# With project directory
happy --dir ~/projects/my-app
 
# With session name
happy --session-name "backend-api"
 
# With custom port
happy --port 8766

# List active sessions
happy list
 
# Show session details
happy info --session-id abc123

# Check if everything works
happy doctor
 
# Test Claude Code integration
happy test

# Custom port
happy --port 9000
 
# Custom relay server
happy --server https://relay.mycompany.com
 
# LAN-only mode
happy --no-relay --host 0.0.0.0

# Named session
happy --session-name "feature-branch"
 
# Resume session
happy --session-id abc123def456
 
# Headless for CI/CD
happy --headless --session-name "ci-build"

# Specific Claude Code binary
happy --claude-path /usr/local/bin/claude-code
 
# Use different model
happy --model sonnet-4
 
# Start with agent
happy --agent bedtime
 
# Custom MCP config
happy --mcp-config ~/work-mcp-tools.json

# Text code for manual entry
happy --no-qr
 
# Require authentication
happy --require-auth

# Debug mode
happy --verbose
 
# Quiet mode for scripts
happy --quiet --json

# Pass model and token settings
happy -- --model opus-4.1 --max-tokens 10000
 
# Pass a specific task
happy -- "refactor the auth system"
 
# Combine Happy and Claude options
happy --port 9000 -- --model sonnet-4 --verbose

# Set default server
export HAPPY_SERVER_URL="https://relay.mycompany.com"
happy  # Uses company relay
 
# Disable telemetry
export HAPPY_TELEMETRY=false
 
# Debug logging
export HAPPY_LOG_LEVEL=debug
happy

{
  "server": "https://relay.company.com",
  "port": 8766,
  "session_name": "my-project",
  "claude_args": ["--model", "opus-4.1"],
  "mcp_config": "./project-mcp.json"
}

{
  "server": "https://relay.happy.engineering",
  "encryption": "aes-256-gcm",
  "telemetry": false,
  "theme": "dark",
  "notifications": true
}

happy list [options]
 
Options:
  --all          Show all sessions (including inactive)
  --json         Output as JSON
  --verbose      Show detailed info

happy info [options]
 
Options:
  --session-id   Session to inspect (required)
  --json         Output as JSON

happy kill [options]
 
Options:
  --session-id   Session to kill (required)
  --all          Kill all sessions
  --force        Force kill without confirmation

happy doctor [options]
 
Options:
  --verbose      Show detailed diagnostics
  --fix          Attempt to fix issues

✓ Node.js 18.0.0
✓ Claude Code detected
✓ Network accessible
✓ Encryption working
✓ Relay server reachable

# Show current config
happy config show
 
# Set a value
happy config set server https://relay.company.com
 
# Get a value
happy config get server
 
# Reset to defaults
happy config reset

happy logs [options]
 
Options:
  --session-id   Session to view (default: current)
  --tail         Follow log output
  --lines N      Show last N lines
  --grep PATTERN Filter logs

# GitHub Actions example
- name: Run Claude Code Analysis
  run: |
    happy --headless \
      --session-name "pr-${{ github.event.number }}" \
      -- "review this PR and suggest improvements"

# Terminal 1: Frontend
happy --port 8765 --session-name frontend
 
# Terminal 2: Backend  
happy --port 8766 --session-name backend
 
# Terminal 3: Database
happy --port 8767 --session-name database

#!/bin/bash
# Start Happy in background
happy --headless --session-name batch &
HAPPY_PID=$!
 
# Wait for connection
sleep 5
 
# Send commands via API
curl -X POST http://localhost:8765/api/message \
  -d '{"text": "generate tests for user.js"}'
 
# Cleanup
kill $HAPPY_PID

# Run in container
docker run -it \
  -v $(pwd):/workspace \
  -p 8765:8765 \
  happycoder/cli \
  --dir /workspace
 
# With docker-compose
services:
  happy:
    image: happycoder/cli
    ports:
      - "8765:8765"
    volumes:
      - .:/workspace
    command: --dir /workspace --headless

# Verbose connection logs
happy --verbose --log-level debug
 
# Test relay server
curl https://relay.happy.engineering/health
 
# Check local port
lsof -i :8765

# Kill all sessions
happy kill --all
 
# Clear config
happy config reset
 
# Remove all data
rm -rf ~/.config/happy
rm -rf ~/.happy

# Increase message buffer
happy --buffer-size 10000
 
# Reduce encryption overhead (less secure)
happy --encryption aes-128-gcm
 
# Optimize for slow networks
happy --compression gzip

if happy test; then
  echo "Happy Coder is working!"
else
  echo "Something's wrong, exit code: $?"
fi

# Show help
happy --help
 
# Show version
happy --version
 
# Show detailed command help
happy [command] --help