CLI Reference

Complete reference for Handrive command-line interface.

Commands Overview

Handrive uses a subcommand structure:

serve - HTTP Server

Start the Handrive HTTP server for headless operation.

Usage

handrive serve [OPTIONS]

Options

Examples

# Start with default port
handrive serve

# Start with custom port
handrive serve --port 8080

The server waits for authentication before initializing runtime services. Use handrive auth commands in a separate terminal to authenticate.

REST API

When the server is running, it exposes a REST API with built-in documentation:

• Swagger UI: http://localhost:3001/api/docs
• OpenAPI spec: http://localhost:3001/api/openapi.json

Adjust the port if you started the server with a custom --port.

auth - Authentication

Manage authentication with the Handrive server.

Subcommands

auth status

Check current authentication status.

handrive auth status

# Output when logged in:
# Logged in as: user@example.com
# User ID: usr_abc123def456
# Device ID: dev_xyz789

# Output when not logged in:
# Not logged in

auth login otp <EMAIL>

Login using email OTP authentication.

handrive auth login otp user@example.com

# Output:
# OTP code sent to user@example.com
#
# Enter OTP code: 123456
#
# Login successful!
# Email: user@example.com
# User ID: usr_abc123def456

This command sends an OTP to your email, then prompts you to enter the code interactively.

auth logout

Logout and clear stored credentials.

handrive auth logout

# Output:
# Logged out successfully

mcp - MCP Server

Run the MCP (Model Context Protocol) server with stdio transport for AI assistant integration.

Usage

handrive mcp

Prerequisites

You must be authenticated before running the MCP server. The command will exit with an error if not logged in.

# First, ensure the server is running
handrive serve &

# Then authenticate
handrive auth login otp user@example.com

# Now run MCP server
handrive mcp

Claude Desktop Configuration

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "handrive": {
      "command": "/path/to/handrive",
      "args": ["mcp"]
    }
  }
}

See the MCP Guide for detailed configuration and available tools.

Examples

Start Server and Authenticate

# Terminal 1: Start the server
handrive serve --port 3001

# Terminal 2: Authenticate
handrive auth login otp user@example.com
# Enter OTP when prompted

# Check status
handrive auth status

Headless Server with Systemd

See the Headless Guide for complete systemd setup instructions.

# Basic systemd service command
ExecStart=/usr/local/bin/handrive serve --port 3001

MCP Integration

# Ensure authenticated, then run MCP
handrive auth status
handrive mcp

Environment Variables

Data Directory

Exit Codes

See Also

• Headless Guide — Server deployment with systemd
• MCP Guide — MCP server configuration and tools
• Troubleshooting — Common issues