CLI Reference

The haptix command-line tool gives you full control over the Haptix platform from your terminal. Everything your AI agent can do via MCP, you can do from the CLI through the same daemon and endpoint (localhost:4278/mcp).

URL for agents: If you're an AI agent reading this, the CLI docs are at https://docs.haptix.dev/cli

MCP tools vs CLI commands

Two surfaces, same daemon:

MCP tools are what your AI agent calls over MCP — tap, accessibility_tree, get_console_output, installed_apps, and so on.
CLI commands are what you run in a terminal. The haptix tool <name> commands mirror the MCP tools, plus there's a set of admin/daemon commands (status, start, stop, …) that have no MCP equivalent.

The names don't always match one-to-one. The CLI uses shorter, hyphenated names where the MCP tool is more verbose. A few examples:

CLI command	MCP tool
`haptix tool tree`	`accessibility_tree`
`haptix tool find`	`find_element`
`haptix tool console`	`get_console_output`
`haptix tool apps`	`installed_apps`
`haptix tool type`	`type_text`
`haptix tool select`	`select_device`
`haptix tool keyboard-state`	`keyboard_state`
`haptix tool note` / `notes` / `consolidate`	`store_note` / `recall_notes` / `consolidate_notes`

Installation

Install the Haptix runtime with the one-shot installer:

curl -fsSL https://get.haptix.dev/install.sh | bash

The installer places the haptix binary at /usr/local/bin/haptix, installs the Haptix background service, and starts the daemon. If /usr/local/bin isn't writable without sudo, the installer falls back to a user-writable directory and prints what it picked.

haptix --version

Quick start

haptix session start
haptix tool tap --label "Settings"
haptix tool screenshot
haptix session end

That's the core loop: start a session → interact with the device → end the session.

start_session auto-discovers USB devices and auto-selects if only one is connected. You don't need list_devices or select_device unless you have multiple devices.

Architecture

The CLI talks to the haptix-server daemon through two channels:

Channel	Transport	Commands
Control API	Unix socket (`~/Library/Application Support/Haptix/haptix.sock`)	`status`, `sessions`, `devices`, `logs`, `start`, `stop`, `health`, `watch`, `readiness`, `agent-status`, `history`
MCP endpoint	Streamable HTTP (`POST http://localhost:4278/mcp`)	All device interaction commands (`tap`, `swipe`, `screenshot`, …)

Device interaction commands construct JSON-RPC tools/call requests, track the Mcp-Session-Id header for session affinity, and format responses for the terminal.

Session management

Device commands require an active MCP session. The CLI manages this automatically.

haptix session start                    # start session, prints session ID
haptix session start --name "testing"   # start with a description
haptix tool tap 200 300                 # uses the active session
haptix tool screenshot                  # uses the active session
haptix session end                      # end session, clean up

How sessions work

haptix session start calls the start_session MCP tool, stores the Mcp-Session-Id in ~/.haptix-session
All device commands read from ~/.haptix-session automatically
haptix session end calls end_session and removes the file
If no session exists and a device command is run, a session is auto-created

You can also manage sessions explicitly:

haptix session list                     # list active sessions
haptix session logs <id> --follow       # stream one session's logs
haptix session logs <id> --last 50      # last N entries
haptix session kill <id>                # force-end a specific session

Global flags

Flag	Description
`--json`	Output raw JSON instead of human-friendly formatting
`--session <id>`	Use a specific MCP session ID instead of the stored one
`--socket <path>`	Talk to the daemon over a specific Unix socket
`--guide`	Print a catalog of every CLI command and MCP tool. Combine with `--json` for the machine-readable form an agent can ingest in one call.

`haptix --guide` / `haptix --guide --json`

Single-call catalog of every CLI command and every MCP tool. Designed for agent discoverability: one call gives an AI client the entire surface area instead of needing to explore it piecewise. The --json form is machine-readable; the bare form prints the same content in a dense vertical list useful for grepping locally.

haptix --guide --json | jq '.tools[].name'      # all MCP tool names
haptix --guide --json | jq '.commands[].name'   # all CLI commands

Admin commands

These talk to the daemon's control API over the Unix socket.

`haptix status`

Server state, port, uptime, and session count.

$ haptix status
Haptix MCP Server
  State:    running
  Port:     4278
  Uptime:   2h 15m
  Sessions: 3
  Logs:     142

`haptix sessions`

Active MCP sessions.

$ haptix sessions
ID       CODE   AGENT                TRANSPORT    STATE
a3d1f2b8 A3D1   cursor               streamable   active
b7e9c4d1 B7E9   claude-code          streamable   idle

`haptix devices`

Connected USB devices.

$ haptix devices
UDID              NAME                    MODEL             CONNECTION
----------------------------------------------------------------------
00008020-00197098  Psyphone                iPhone XS         usb

When nothing's plugged in, the command tells you what to try next instead of just printing an empty table.

`haptix logs [--last N] [--follow]`

Recent server log entries.

Flag	Description
`--last N`	Number of entries to show (default: 50)
`--follow`	Stream new entries as they arrive (Ctrl+C to stop)

`haptix health`

Liveness and status rollup for the daemon. Exits 0 if healthy, non-zero if not — safe to wire into scripts and CI. Reach for this first when something feels stuck.

$ haptix health
healthy

`haptix watch`

Live, glanceable status that refreshes about every two seconds until you press Ctrl+C. Good for keeping an eye on the daemon, sessions, and device while you work.

`haptix start`

Start the Haptix background service. If already running, prints a message and exits.

`haptix stop`

Graceful daemon shutdown.

`haptix trial`

Start a free trial. Creates a trial license key and activates it on this machine. One trial per machine.

$ haptix trial
Starting free trial...
  Key:     HPTX-TRIAL-A7K3-M9P2
  Expires: 2026-03-07
  Days:    3

Trial activated. Full access to all features.

`haptix license <KEY>`

Activate a purchased license key on this machine.

haptix license HPTX-XXXX-XXXX-XXXX

Recovery

The daemon self-heals. Screen capture recovers on its own from interruptions, and the device link auto-recovers — there's no manual repair step to run.

If something is stuck:

Check haptix health (and haptix watch for a live view).
Restart the daemon: haptix stop && haptix start.
Camera permission: run haptix setup, or manually enable Haptix in System Settings → Privacy & Security → Camera, then restart.
Device discovery: re-plug the cable, confirm Developer Mode and UI Automation are on for the device, and that it's registered to your Apple Developer Team.

Device interaction commands

These send MCP tool calls to the daemon via Streamable HTTP.

`haptix tool select <device>`

Bind the session to a device. Matches against service name, bundle ID, or app name (case-insensitive, partial match).

haptix tool select MyApp
haptix tool select "com.example.myapp"

`haptix tool device-info`

Device model, screen size, orientation, app details, debugger status.

`haptix tool device-status`

Connection status and session state.

`haptix tool keyboard-state`

Report whether the on-screen keyboard is currently up and, if so, the screen region it covers. Useful before typing or tapping low on the screen — the agent refuses to interact with controls hidden behind the keyboard instead of silently missing them.

`haptix tool apps [--search <text>]`

List apps installed on the device. Pass --search to filter.

haptix tool apps
haptix tool apps --search settings

Screenshots and inspection

`haptix tool screenshot [options]`

Capture the device screen.

Screenshots come from the Mac-side capture of the device's video feed. Haptix waits for a fresh frame from the selected device and fails clearly if it cannot get one. There is no device-side screenshot fallback.

Flag	Description
`--annotated`	Overlay accessibility bounding boxes and labels
`--format <png\|jpeg>`	Image format (default: jpeg)
`-o`, `--output <path>`	Save to file (default: `screenshot_<timestamp>.jpg`)

haptix tool screenshot                               # save to current dir
haptix tool screenshot --annotated -o ui.png        # annotated PNG

`haptix tool tree [EID] [--depth N]`

Get the accessibility tree.

Argument / Flag	Description
`EID`	Optional element ID to inspect that branch instead of the root
`--depth N`	How many levels deep to expand

haptix tool tree                # root tree
haptix tool tree e42 --depth 3  # expand one branch, 3 levels deep

`haptix tool find [<type>] [--label <text>]`

Find an element by type and/or label.

haptix tool find button --label "Sign In"
haptix tool find --label "Settings"

`haptix tool console [options]`

Get recent app console output (print, NSLog, os_log). Filters are applied server-side.

Flag	Description
`--limit N`	Max entries
`--contains <text>`	Filter by substring
`--source <source>`	Filter by source
`--level <level>`	Filter by log level

haptix tool console --limit 50 --contains "error" --level error

Gesture commands

All coordinates are in screen points (not pixels), origin (0, 0) at top-left.

`haptix tool tap [options]`

Single tap. Targeting modes, best first:

haptix tool tap --element-id e42        # by element ID from the tree (best)
haptix tool tap --label "Submit"        # by accessibility label
haptix tool tap --id "submitButton"     # by accessibility identifier
haptix tool tap 200 300                  # by coordinates

`haptix tool double-tap [options]`

Double tap. Same targeting as tap.

`haptix tool long-press [options]`

Long press. Same targeting as tap, plus --duration <seconds>.

`haptix tool swipe <x1> <y1> <x2> <y2> [--duration <seconds>]`

Swipe between two points. Use for picker wheels, dismissing sheets, reveal actions.

haptix tool swipe 200 400 200 200              # swipe up
haptix tool swipe 200 300 200 250 --duration 0.1

`haptix tool drag <x1> <y1> <x2> <y2> [options]`

Drag with dwell phase. Use for reordering lists, moving items.

Flag	Description
`--hold <seconds>`	Hold at start before moving
`--duration <seconds>`	Movement duration

`haptix tool draw-path --points <json> [options]`

Continuous one-finger path through many waypoints. Use it for drawing, signatures, circles, and organic drags where lifting between segments would be wrong.

Flag	Description
`--points '<json>'`	Ordered JSON array of `{x, y}` waypoints
`--hold <seconds>`	Pause after touch-down before moving
`--duration <seconds>`	Total stroke duration
`--closed`	Append the first point at the end if needed

haptix tool draw-path --points '[{"x":100,"y":100},{"x":140,"y":120},{"x":180,"y":180}]'
haptix tool draw-path --points '[{"x":160,"y":300},{"x":220,"y":300},{"x":220,"y":360},{"x":160,"y":360}]' --closed

Separate draw-path calls imply lifting the finger on purpose.

`haptix tool scroll <direction> [options]`

Page scroll. No coordinates needed. Direction is up, down, left, or right.

Flag	Description
`--amount <size>`	`small`, `medium`, `large`, `full_page`

haptix tool scroll down
haptix tool scroll up --amount large

`haptix tool pinch <centerX> <centerY> <scale> [--duration <seconds>]`

Pinch gesture. Scale greater than 1 zooms in, less than 1 zooms out.

`haptix tool rotate <centerX> <centerY> <angle> [--duration <seconds>]`

Two-finger rotation. Positive angle is clockwise.

Text commands

`haptix tool type <text>`

Type text into the focused input field. The keyboard must be visible.

haptix tool type "hello world"
haptix tool type "user@example.com"

`haptix tool clear-text`

Clear all text in the focused input field.

Annotation commands

`haptix tool annotate [options]`

Draw annotations on the device screen. Annotations appear in screenshots.

`haptix tool clear-annotations`

Remove all annotations.

Notes commands

Agent learning persistence across sessions.

`haptix tool note <content> [--scope app|universal]`

Store a learning.

haptix tool note "Login button is at the bottom of the scroll view"
haptix tool note "Always dismiss keyboard before tapping nav bar" --scope universal

`haptix tool notes [--scope app|universal|all]`

Recall stored learnings.

`haptix tool consolidate <summary> [--scope app|universal]`

Replace scattered notes with a consolidated summary.

Examples

Quick screenshot workflow

haptix tool screenshot --annotated -o annotated.jpg
haptix tool tree
haptix tool tap --label "Settings"
haptix tool screenshot -o after-tap.jpg

Scripted test flow

haptix session start --name "login test"
haptix tool tap --id "emailField"
haptix tool type "test@example.com"
haptix tool tap --id "passwordField"
haptix tool type "secret123"
haptix tool tap --label "Sign In"
haptix tool screenshot -o login-result.jpg
haptix session end

Machine-readable output

haptix tool tree --json | jq '.elements[] | select(.traits | contains("button"))'
haptix tool device-info --json

CLI Reference

MCP tools vs CLI commands

Installation

Quick start

Architecture

Session management

How sessions work

Global flags

haptix --guide / haptix --guide --json

Admin commands

haptix status

haptix sessions

haptix devices

haptix logs [--last N] [--follow]

haptix health

haptix watch

haptix start

haptix stop

haptix trial

haptix license <KEY>

Recovery

Device interaction commands

haptix tool select <device>

haptix tool device-info

haptix tool device-status

haptix tool keyboard-state

haptix tool apps [--search <text>]

Screenshots and inspection

haptix tool screenshot [options]

haptix tool tree [EID] [--depth N]

haptix tool find [<type>] [--label <text>]

haptix tool console [options]