# linkshell-cli Follow, steer and approve the coding agents running on your computer — from your phone. This is the computer side of [LinkShell](https://github.com/LiuTianjie/LinkShell): it runs Claude Code, Codex and other agents you already have installed, and keeps them reachable from the LinkShell app ([iPhone](https://apps.apple.com/cn/app/linkshell/id6761547516) · [Android](https://github.com/LiuTianjie/LinkShell/releases/latest)) over an end-to-end encrypted channel. [Website](https://liutianjie.github.io/LinkShell/) · [Docs](https://liutianjie.github.io/LinkShell/docs/) · [简体中文](https://github.com/LiuTianjie/LinkShell/blob/main/README_CN.md) ## Install macOS or Linux, **Node.js 22.13 or newer**. ```bash npm i -g linkshell-cli linkshell setup ``` `linkshell setup` does everything once, in order: it starts the host in the background, gets the screen ready (on a Mac, the two permission switches), and connects your phone. Each part also has its own command. Connect your phone one of two ways: - **Official gateway (iTool membership).** `linkshell login`, then sign in to the app with the same account, and the computer shows up by itself. - **Your own gateway.** Run one (below), then: ```bash linkshell host --gateway wss://gw.example.com --daemon linkshell pair # scan the QR code in the app ``` Buy LinkShell on its own (CNY 9.9/month or 49/year; USD 3.19/month or 13.49/year), or choose the all-products annual bundle (CNY 99 or USD 26.49). Prices include tax. [Choose a plan on iTool](https://www.itool.tech/en/pro?product=linkshell) with the same account; Alipay is one-time and Creem renews automatically until canceled. Refresh membership in the desktop app or web workspace after purchase. Existing access and referral rewards are preserved. Start sessions from the phone, or launch agents from your terminal so they can be handed over at any time: ```bash linkshell claude # Claude Code; a message from the phone takes over, any key here takes it back linkshell codex # Codex; the terminal and the phone are live at the same time ``` Claude Workflow progress, phases and Agent details require CLI 0.10.6 or newer and app 2.3.5 or newer. CLI 0.10.40 and newer automatically reconcile the running host with `linkshell upgrade`. CLI 0.10.19 includes Host 0.4.19 session recovery fixes: stale running states, Codex native archives, missing Claude history and lazy ACP reconnection. This update needs only the computer-side CLI and a host restart; no mobile app, gateway or screen-helper update is required. ## Remote screen On Apple silicon and Intel Macs with macOS 13+, the CLI includes the signed universal LinkShell.app. macOS selects the native architecture automatically for screen capture, H.264 encoding and input; low-latency encoding is used where available. `linkshell screen` sets up Screen Recording and Accessibility; `--check` reports permissions and availability, not media performance. Linux viewing requires ffmpeg and an X11 display and has no input control. Supported iOS app builds receive native WebRTC video and present it with Metal, requesting up to 120 fps within source/receiver, power, thermal and network limits. They automatically try standard WebView video and then RPC fallback if needed. A native receiver change needs a new iOS app binary as well as any required computer-side update. See the [architecture and validation limits](https://github.com/LiuTianjie/LinkShell/blob/main/docs/v2/screen-realtime.md); a 120 fps request does not establish sustained 120 fps or stable 4K/60. ## Commands | | | | --- | --- | | `linkshell setup` | Set this computer up, once: the host, the screen's permissions, your phone | | `linkshell host --daemon` | Start LinkShell in the background | | `linkshell status` | The host, its agents, sessions and gateway connection | | `linkshell host stop` | Stop the host (`linkshell stop` stops everything LinkShell runs here) | | `linkshell host --gateway ` | Choose the gateway (`off` to disconnect, `default` for the official one); applies to a running host | | `linkshell host --lan [port]` | Connect over same-Wi-Fi LAN (starts a local gateway on ``, default 8787; `off` to disable) | | `linkshell host --keep-awake ` | Idle sleep prevention: `smart` (default, while active), `always`, or `off` | | `linkshell pair` | Pair a phone through your own or LAN gateway | | `linkshell devices` | Paired phones; `linkshell devices remove ` unpairs one | | `linkshell login` / `logout` | iTool account: join or leave the official gateway, without restarting the host | | `linkshell claude` / `linkshell codex` | The agent's own UI, shareable with the phone (arguments pass through) | | `linkshell gateway [--port 8787] [--daemon]` | Run a gateway (`gateway status`, `gateway stop`) | | `linkshell screen` | Set up watching and controlling the screen (`--check` only reports) | | `linkshell doctor` | Check Node, agents, the host and its gateway | | `linkshell upgrade` | Upgrade the CLI and restart an outdated running host; preserve login, pairing and history | ## Run your own gateway A gateway only relays encrypted frames and brokers pairing. Yours is the same program as the official one, without the accounts: you pair each phone once, with a QR code or a six-digit code. ```bash linkshell gateway --port 8787 --daemon ``` or with Docker: `nickname4th/linkshell-gateway` (see the [self-hosting guide](https://github.com/LiuTianjie/LinkShell/blob/main/docs/deploy.md)). Put it behind HTTPS and point hosts at `wss://your-domain`. All it keeps is one SQLite file, `~/.linkshell/relay.db`: keep it and phones stay paired. ## Files ``` ~/.linkshell/ ├── state.db sessions and their history ├── identity.json this computer's keys ├── paired-devices.json phones paired with it ├── auth.json the iTool account login, if any ├── config.json the chosen gateway ├── host.log the host's log ├── worktrees/ git worktrees made for sessions started (or forked) into one ├── LinkShell.app the Mac side of the screen, unpacked on first use (macOS) └── relay.db pairings, when this computer runs a gateway ``` `LINKSHELL_HOME` moves this directory. LinkShell never handles your agents' accounts or API keys: agents run as you, with your login shell's environment. ## Coming from 1.x 2.0 changed both the app and the computer side: upgrade both and connect again. From 0.10 the 1.x commands (`linkshell start`, `linkshell list`) are gone, and `linkshell gateway` no longer serves the 1.x app. `linkshell stop` still ends a 1.x bridge left running from before the upgrade. `linkshell upgrade` uses the newly installed CLI to restart an outdated running host, even when the CLI is already at the latest version. It retains the same home, identity, login and paired devices, waits for the gateway to reconnect, and leaves a stopped host stopped. Running agent turns and terminal processes stop during the restart; saved sessions remain available. The restart worker continues independently if an upgrade closes the host-owned terminal that launched it; its progress is in `~/.linkshell/upgrade.log` (or `LINKSHELL_HOME`). The first upgrade from a CLI older than 0.10.40 still runs the old updater. Once installation finishes, run `linkshell upgrade` again to bring the host forward. Subsequent upgrades need one invocation. ## License MIT