# cli-connect

<img src="assets/cli-connect-logo.png" alt="cli-connect logo" width="128">

Control your Mac or Windows terminal from your iPhone.

## Install

```bash
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:
   ```bash
   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

```bash
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 "<name>"** — 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:

```bash
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

```bash
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
```bash
sudo cp $(which cli-connect) /usr/local/bin/cli-connect
# Then a LaunchAgent — see PLAN.md M8.
```

### Windows
```powershell
$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>
