CLI Reference

The Handrive CLI (hand) provides complete command-line access to manage shares, files, contacts, and transfers.

Installation

The CLI is included with Handrive. After downloading, the hand command is available in your terminal.

Quick Start

# Start the server (required for CLI commands)
hand serve

# In another terminal, authenticate
hand auth login otp your@email.com

# Create a share
hand shares create "My Files" ~/Documents

# List your shares
hand shares list

Environment Variables

VariableDescriptionDefault
HANDRIVE_API_URLAPI base URL for CLI commandshttp://127.0.0.1:4263

Commands

hand serve

Start the HTTP server for headless operation

hand auth

Authentication commands (status, login, logout)

hand shares

Create and manage file shares

hand files

List, search, and manage files within shares

hand members

Manage share access and member permissions

hand contacts

Manage your contact list

hand users

Profile management and user search

hand transfers

P2P file transfers between devices

hand discovery

Discover shares from other devices

hand mcp

Run MCP server for AI assistant integration

hand service

Install and manage Handrive as a system daemon

Output Format

List commands display tabular output:

$ hand shares list
ID                                    NAME              PATH
--------------------------------------------------------------------------------
abc123-def456-789...                  My Documents      /Users/me/Documents
xyz789-abc123-456...                  Project           /Users/me/project

Detail commands display key-value pairs:

$ hand shares get abc123
ID: abc123-def456-789...
Name: My Documents
Local Path: /Users/me/Documents
Device ID: device-123...
Local: true

Error Handling

Errors are printed to stderr with the HTTP status code:

$ hand shares get invalid-id
Error 404: {"error":"Share not found"}

See Also