CLI reference

pterm is the Termivoa host program. pterm help (or --help, -h) prints this command list. On Windows, use .\pterm.exe unless pterm is on your PATH.

Background processes: the broker owns sessions; the gateway serves the phone page on 127.0.0.1:8787.

Set up, start and stop

Command	What it does
pterm setup	First run: checks, one confirmation, startup at login, phone address, Tailscale Serve (asks first), pairing. It refuses before any change while other Tailscale Serve handlers share this computer’s Termivoa address (port 443); see Setup refuses other Tailscale Serve handlers. It then exits with code 3; other errors exit with 1.
pterm setup --verbose	pterm setup prints a short plan, one line for each change, and any warning of the checks under Warnings:. --verbose also prints the checks, the startup files and every command.
pterm setup --apply --yes	Installer mode: registers startup, asks nothing, sets the phone address only if unset, never changes Tailscale or pairs a phone. It refuses in the same way.
pterm doctor	Read-only checks. Never prints secrets. It also shows the protocol revision and multi-computer checks.
pterm config origin [<url>]	Shows or sets the phone’s private HTTPS address.
pterm launch [--no-open]	Starts the broker and gateway if needed, and opens the local page. While Tailscale Funnel is on for port 443 or 8443, it first prints a warning with the command that turns Funnel off.
pterm stop	Stops only the gateway. Sessions keep running, but phones cannot connect.
pterm shutdown	Asks first, ends all sessions, and stops the broker and gateway.
pterm uninstall [--dry-run] [--yes] [--delete-data]	Removes startup at login. Deletes data only with --delete-data.
pterm up --dev [--data-dir <dir>] [--runtime-dir <dir>] [--listen <addr>] [--preview-listen <addr>|off]	Development only: an isolated test copy that leaves your real setup alone.

--dev and --runtime-dir <folder> are for development tests only.

Pair and manage phones

Command	What it does
pterm pair [--origin <url>] [--no-qr] [--no-wait]	Prints a two-minute, single-use pairing link and QR code, then approves the phone after you compare codes. Every pterm pair that pairs (also --via and approve) refuses while Tailscale Funnel is on for port 443 or 8443; see troubleshooting.
pterm pair pending	Shows phones waiting for approval, with their codes.
pterm pair approve <pending-id>	Approves a phone after you compare its code.
pterm devices	Shows paired phones, status and last use. A VIA column shows the home address a phone uses this computer from (- for this computer’s own page).
pterm devices rename <device-id> <label>	Renames a paired phone.
pterm revoke <device-id>	Asks first, then removes a phone’s access at once.

The pairing link and QR code are secret. Do not share them.

Use several computers

See Use several computers.

Command	Where	What it does
pterm pair --via <name|url>	New computer	Prints a two-minute, single-use add-computer link for the Termivoa app at home and, on a terminal wide enough for it, a QR code of that link, then approves the phone after you compare codes. <name> is home’s machine name, such as mac; <url> is its full address. It tells you to tap the link in a Termivoa session and confirm “Add this computer?”, or, in Settings → + Add a computer, to scan the QR code (Scan QR) or paste the link. Scan it in the app, not with the phone’s Camera app: that opens the browser. In a terminal it also shows this computer in the app at home under Settings → Found on your network, with Add, and waits up to 10 minutes (it prints “Sent to mac (https://…).”). Then it shows the QR code and the link only when you press Enter (“No Add button? Press Enter to show a QR code and a link.”); when nothing reached home, it prints them at once. The prompt starts Phone "iPhone" wants to add this computer (vps) to your Termivoa app on mac., and success says Done. vps is in your Termivoa app on mac. Open the app and tap it. When the link expires and nothing reached home, it ends as before. With piped input or --no-wait it sends nothing to home. pterm setup does the same when you answer 2 to Is Termivoa already on your phone?; its list shows each computer’s full address and system. See How do I add a computer?
pterm pair --via <name|url> --allow-tagged	New computer	The same, when home or this computer is a tagged Tailscale node. Check the tags first. Add does not work for a tagged computer: use the QR code or the link.
pterm pair pending	New computer	Also shows a VIA column: the home app a waiting phone comes from.
pterm computers	Home	Shows each phone’s other computers: device ID, label, address and when added.
pterm computers remove <url>	Home	Removes a computer from every phone’s list. It does not sign the phones out there; run pterm revoke on that computer.
pterm revoke --via <url>	Peer	Asks first, then revokes every phone that uses this computer from the Termivoa app at <url>, and deletes that app’s pairing links and pending pairings. It does this also when no phone uses it now. Use it if home was hacked.
pterm revoke <device-id>	Home	After it revokes the phone, also lists the other computers that phone used, so you can revoke it there too.

pterm pair --via also takes --no-qr, --no-wait and --origin. --allow-tagged needs --via.

pterm revoke --via asks one of these:

Revoke browser access for 2 device(s) that use this computer from the Termivoa app at https://mac.tailx.ts.net? Their live connections close now. [y/N]
No device uses this computer from the Termivoa app at https://mac.tailx.ts.net now, but its pending pairings and pairing links will be removed. Continue? [y/N]

pterm doctor adds these lines:

Line	What it means
protocol revision 1 (oldest supported 1)	This computer’s protocol version, for updating computers one at a time.
multi-computer: CORS list (bound app origins): …	Home addresses that phones use this computer from. no bound app origins (CORS off) means none.
multi-computer: pairing CORS list (pending pairings): …	Home addresses of pairings that wait for approval.
! multi-computer: <url>: owner mismatch …, node ID changed (reused name?), pinned node … is gone, different tailnet; not supported	A home that phones use this computer from fails the Tailscale check. Owners are compared by Tailscale user ID, not by login name.
! multi-computer: <url>: tags changed since pairing; phones bound to it are refused until paired again	Home’s Tailscale tags were added, removed or replaced after pairing. Pair again.
! multi-computer: this computer's tailnet is unknown (is Tailscale logged out?); bound app origins cannot be checked	This computer is not logged in to Tailscale. Log in.
! tailscale serve: other handlers share this computer's Termivoa origin https://…: …	A problem: Tailscale Serve shares more than Termivoa on this address (port 443). Move each handler to another computer or to its own Tailscale Service hostname (another port does not help); the line prints the commands that remove them. pterm setup refuses until you do.
! tailscale serve (warning): other ports of this computer's host receive the Termivoa cookie, …	A warning, not a problem: handlers on other ports of this computer get the Termivoa cookie when the phone opens them. See the troubleshooting entry.
herdr: <path> <version> (protocol <n>), server running at <socket>, can make worktrees	Next beta. herdr is installed and its server runs. The line says “cannot make worktrees” when herdr cannot. herdr: <path>, server not running (<socket>) means the server is off. These lines show only when herdr is installed and are never a problem. See Termivoa + herdr.
! herdr: <path>, Termivoa will not use the server socket <socket>: group or others can write <folder>; run: chmod go-w <folder>	Next beta. herdr runs, but another user could reach its socket, so Termivoa does not use it and the app says “herdr is not running”. Run the command the line prints. See the troubleshooting entry.
herdr agents the phone can start: claude, codex	Next beta. The agents that already run in herdr, which New worktree offers.
! herdr: <path> <version> (protocol <n>) is too old or unreadable; update herdr (0.8.2 or later)	Next beta. Update herdr. See Update herdr on mac.
! herdr: config.toml sets a prefix key other than ctrl+b; …	Next beta. Termivoa doubles only ctrl+b, so a phone can send that other prefix key to a herdr terminal it opened. At worst it detaches the phone. Set herdr’s prefix key back to ctrl+b.
! herdr at <path>: <reason>; Termivoa will not run it	Next beta. It shows before the herdr line, or alone when no other herdr is found. Termivoa refused a herdr program, for example one that belongs to another user or sits in a folder that others can write.
GitHub: connected as <login> or GitHub: not connected	Next beta. Whether this computer is connected to GitHub. It shows only when the broker runs and the build has GitHub, and is never a problem. See Set up a GitHub repository.
! tailscale at <path>: …; Termivoa will not run it	Another user could replace that Tailscale CLI, so Termivoa does not use it. See the troubleshooting entry.

Work with sessions

Command	What it does
pterm list	Shows sessions and their state.
pterm new --project <id> --shell <id>	Starts a session with control.
pterm attach [--control] <session-id>	Opens a session in this terminal, read-only unless --control.
pterm terminate <session-id>	Asks first, then ends the session and all it started.

In pterm attach, Ctrl+] leaves without ending the session. With control, Ctrl+V then Ctrl+] sends a real Ctrl+].

Save projects and shells

Command	What it does
pterm project add [--name <name>] <path>	Saves a project folder where new sessions start.
pterm project list	Shows saved projects with IDs.
pterm profile list	Shows saved shell profiles with IDs.
pterm profile detect	Finds this computer’s shells and saves them as profiles.

GitHub

Next beta. See Set up a GitHub repository. You connect a computer in the app: in Settings, tap the computer’s card, then Connect. There is no command to connect.

Command	What it does
pterm github status	Prints one line, for example GitHub: connected as octo-demo, GitHub: not connected, GitHub: connecting, GitHub: git is not installed on this computer or GitHub: not available in this build.
pterm github disconnect	Removes this computer’s GitHub login at GitHub and on the computer, then prints GitHub: disconnected and the address of GitHub’s Authorized GitHub Apps page, where you can check that Termivoa is gone.
pterm github-credential	Used by git in a folder that Termivoa cloned, to get the GitHub login. Do not run it yourself.