Command reference

Most of remotxai happens in the app. These are the commands you run on your computer.

Install

curl -fsSL https://app.remotxai.com/install.sh | sh

Installs remotxai and starts its background service. See Install on your computer.

Connect the computer to your account: remotxai up

remotxai up

Prints a code and a web page. Open the page, approve this computer, then type your account email back at the terminal to confirm. It needs an interactive terminal.

On a computer that is already connected, remotxai up shows its status and reconnects it after remotxai down. remotxai down disconnects without removing the computer from your account.

Pair a phone: remotxai pair

Command	What it does
remotxai pair	Opens pairing and waits for the phone’s verification code.
remotxai pair setup	Prints the QR code and the links.
remotxai pair enable 10m	Opens a pairing window for 10 minutes (the longest allowed).
remotxai pair list	Lists paired phones with their fingerprints and roles.
remotxai pair revoke <prefix>	Removes the phone whose fingerprint starts with <prefix>.
remotxai pair role <prefix> <role>	Changes a phone’s role: viewer, approver, driver or admin.

Steps: Pair your phone.

Check the setup: remotxai doctor

remotxai doctor

Prints PASS, WARN, FAIL or SKIP for each check. It exits with an error if any check fails. Add --json for machine-readable output. It prints no keys or settings.

Upgrade: remotxai upgrade

remotxai upgrade --check
remotxai upgrade

--check reports whether a newer version exists and downloads nothing. remotxai upgrade installs it, and asks before it restarts a running service, because a restart stops running sessions. To go back, run remotxai service rollback.

Switch a session’s profile: remotxai sessions switch-profile

remotxai sessions
remotxai sessions switch-profile <session-id> <profile>

remotxai sessions lists session IDs. The switch moves a running Claude Code, Codex or Pi session to another profile of the same agent, keeping the conversation. It is refused while a turn, an approval or a tool call is running.

Exit code	Meaning
0	Switched.
3	Refused. Nothing changed.
4	The agent did not start, so the session went back to the old profile.
5	The switch stopped halfway. Run remotxai sessions clear-switch-recovery <session-id> after you check which account is running.

More: Profiles and accounts.