cli-connect

Control your Mac or Windows terminal from your iPhone.

Install

brew install errr0rr404/tap/cli-connect    # macOS / Linux
# or
npm install -g @worldofz/cli-connect       # any OS, including Windows

(Requires Node 18+. The package bundles native binaries for darwin-arm64, darwin-x64, linux-x64, and win32-x64. The Node wrapper picks the right one at runtime.)

Pair with your iPhone

1. Install the cli-connect iOS app from TestFlight / the App Store.
2. Sign in (Apple or Google).
3. On the machine you want to control, run:

   cli-connect login

   The CLI prints a code, e.g.:

   ┌──────────────────────────────────────────────────────────────
   │ Open the cli-connect app on your iPhone (signed in)
   │ → Add Machine → enter this code:
   │
   │       ABCD-1234
   │
   │ This code expires in 15 minutes.
   └──────────────────────────────────────────────────────────────
   Waiting for confirmation....

4. On your iPhone, tap + → Add Machine → Code, type the code, tap Pair.
5. Back in the CLI, you'll see ✓ Logged in as "your-machine".

Run the agent

cli-connect serve

Listens on port 8910 by default. The iOS app connects directly to your machine over your LAN (or Tailscale, for cellular). Backend mediates pairing only — terminal traffic doesn't go through it.

Persistent tmux sessions

Tmux sessions survive disconnects forever (unlike a plain shell, which the agent only buffers for ~60s). When the iOS app opens the connect screen for a host, it auto-discovers tmux and shows:

• Resume "" — one tap back into the last session you used.
• A list of every running tmux session with kill / rename actions.
• A + New session row pre-filled with the last name you typed (defaults to main).

Long-press a host in the list to skip the picker and jump straight back into your last session.

To pair the desktop and iPhone on the same tmux session, start it on the desktop and detach:

tmux new -s main
your-agent           # e.g. an AI CLI you want to keep an eye on
# Ctrl-b, then d

Then run cli-connect serve and on the iPhone tap Resume "main".

On Windows, install tmux in WSL. The agent detects WSL and runs wsl.exe tmux ... for you.

Other commands

cli-connect status        # show the saved login info
cli-connect logout        # forget the saved token
cli-connect serve --help  # all serve options

Auto-start at login

macOS

sudo cp $(which cli-connect) /usr/local/bin/cli-connect
# Then a LaunchAgent — see PLAN.md M8.

Windows

$action = New-ScheduledTaskAction -Execute (Get-Command cli-connect).Source -Argument "serve"
$trigger = New-ScheduledTaskTrigger -AtLogOn
Register-ScheduledTask -TaskName "cli-connect" -Action $action -Trigger $trigger

Where things live

• Saved token: ~/Library/Application Support/cli-connect/agent.json (macOS), %APPDATA%\cli-connect\agent.json (Windows), ~/.config/cli-connect/agent.json (Linux). Mode 0600.
• Backend: https://backend-production-a2f85.up.railway.app (the agent talks to this only during login and for periodic heartbeats).

What this is

cli-connect speaks a small WebSocket-based protocol to expose a real PTY (so vim/htop/tmux work) gated by HMAC-SHA256 derived from a per-machine secret issued at pairing time.

Source: https://github.com/Errr0rr404/cli-connect