@worldofz/cli-connect

Control your Mac, Windows, or Linux terminal from your iPhone, Android phone, or another paired desktop.

This npm package ships the cross-platform Go agent (cli-connect, currently 0.1.9) as a single tarball with native binaries for darwin-arm64, darwin-x64, linux-x64, linux-arm64, win32-x64, and win32-arm64. Requires Node ≥ 18. A Node shim picks the right binary. Copilot+ / Snapdragon PCs use win32-arm64 — npm install -g @worldofz/cli-connect is enough; no repo clone.

Install

npm install -g @worldofz/cli-connect

Homebrew is also supported:

brew install errr0rr404/tap/cli-connect

First-time pair

cli-connect login
# Confirm at the printed /pair URL (browser Google/Apple) or in the phone app.

The CLI prints an 8-character code and a /pair URL. Open that URL in a browser (Google/Apple sign-in — no phone app required), or type the code in the cli-connect iPhone/Android app.

Run

cli-connect serve [--port N] [--shell PATH]
cli-connect attach [name] [--id <uuid>]   # drive another paired (or guest) machine
cli-connect share list|allow|deny         # which tmux sessions guests may use
cli-connect invite create|list|revoke     # host invite codes / friend invites
cli-connect invite redeem|pending|accept  # guest
cli-connect status
cli-connect logout

Guest redeem needs a session JWT (saved by login, or CLI_CONNECT_SESSION_TOKEN). Point a dev backend with CLI_CONNECT_BACKEND_URL. Pick a shared tmux session non-interactively with CLI_CONNECT_SHARE_SESSION.

serve runs in the foreground. To run on login:

• macOS → scripts/install-launchd-mac.sh (installs a per-user LaunchAgent)
• Windows → scripts/install-task-scheduler-windows.ps1 (Scheduled Task)
• Linux → ship under your favourite supervisor (systemd --user, runit, …)

How it works

The agent opens a persistent WebSocket to the cli-connect backend. When your phone (or another paired machine) wants a session, the backend forwards bytes between the two sides — no inbound port on this machine, no NAT punching, no Tailscale needed.

serve also listens on the LAN (ws://0.0.0.0:8910), so the phone can connect directly when on the same Wi-Fi or tailnet — pick Auto / Direct / Relay on the app's Connect screen. Use --port N to change the listen port.

Full docs

Complete documentation — including iOS/Android app setup, backend deployment, tmux session picker, attach mode, security model — lives in the project README:

→ github.com/Errr0rr404/cli-connect

Issues and source: same link.

License

MIT.