Command reference
Run these on your computer. Everything else happens in the app.
Install
Section titled “Install”curl -fsSL https://app.remotxai.com/install.sh | shInstalls remotxai and starts its service. Details: Install on your computer.
Connect the computer to your account: remotxai up
Section titled “Connect the computer to your account: remotxai up”remotxai upOpens the approve page in your browser with the code filled in. Approve this computer there. The terminal shows the account, the approving browser and the organisation; nothing is typed. The code travels in the part of the address after #, which no server sees. The terminal also prints the page, the code and a check code, so you can open it yourself. It needs an interactive terminal.
Over SSH, without a display or with --no-browser, nothing opens. The terminal prints the page, the code and a QR code. --qr prints the QR code even when a browser opens.
Approving a computer takes a passkey, on the page remotxai up opened or on any device signed in to your account. A computer joining an organisation goes on without asking anything only when the browser it opened hands over through a page on 127.0.0.1 before it finishes; otherwise it asks for your login password or Touch ID, or for the account email where the system can’t ask. It checks its account code against that browser’s own copy, or else trusts it on first use and says so. Either way it stays marked as not compared until remotxai lock verify compares it with a device already in the organisation. remotxai up --verify asks for your account email and both codes before anything is trusted, as earlier versions did. The first computer of a new organisation asks for your Mac’s login password (the one you unlock the Mac with, not a remotxai password) or Touch ID before it creates the organisation.
remotxai up ends with one line: Ready. <computer> is in <organisation>. If something blocks it, such as a pending admin approval, the line says what to do.
On a connected computer, remotxai up prints the same line. After remotxai down, it reconnects. remotxai down disconnects without removing the computer from your account. On a computer in another organisation, remotxai up --org <name> tells you how to move it.
remotxai up --sharedEnrols the computer as shared, or converts a personal computer that is already enrolled. It prints what shared means and asks you to type shared. On a conversion it then waits up to 15 minutes for an organisation owner or admin to approve in the app. See Convert a computer to shared.
Approve your devices
Section titled “Approve your devices”Your organisation’s first browser is the one remotxai up opened on its first computer: Approve on my computer there hands its code to the terminal, which recomputes it, shows the limits and asks for your Mac’s login password or Touch ID. A line above the prompt names the user and says it is not a remotxai password. It works only while that remotxai up is still waiting, up to 10 minutes. If it ended with no browser, run remotxai up again on that computer’s desktop, any time in its 24 hours: it opens your browser on the same step. The first computer needs a desktop session: when the page remotxai up opened doesn’t hand over to the computer within 30 seconds (over SSH, with no display, with --no-browser or --verify, or when you approved on another device), remotxai up stops before it creates the organisation.
Every later browser or phone only signs in, with your passkey, Google, an email link or a recovery code, and that is all it needs to reach your own Personal computers and the computers an organisation shares with you. There is no approval code to type or scan and no other device to reach for.
remotxai devicesOn a connected computer, remotxai devices shows the account code and the latest change code, then lists your devices in the org by number, the numbers revoke and set-ceiling take.
An approval ends after 365 days. From 30 days before, Home lists each device whose approval ends and Account shows the date. A browser that approved the device, or one above that browser in the chain of approvals, can renew it there with Renew and your passkey. It renews the same role and limits for another 365 days. Otherwise the app names the command to run on the first computer: remotxai lock renew <device-id>.
Revoke a lost device: remotxai devices revoke
Section titled “Revoke a lost device: remotxai devices revoke”remotxai devices revoke 2remotxai devices set-ceiling 2 --role viewer --actions noneOn a computer connected as your own, remotxai devices revoke lists your devices and revokes the one you name by list number or device id, after you type its name. It loses access to every computer in the org within seconds and its keys are never trusted again; to use it again it needs new keys and a fresh sign-in with your passkey. If it is the last device that can approve new ones, the command says so first. remotxai devices set-ceiling changes an approved device’s role, computers or account actions, only for a device this computer approved and never above this computer’s own access, after you type the digest of the new limits. Both need an interactive terminal.
From the app, an approved device in Account, Devices offers Revoke. To cut off a lost computer, choose Revoke on it in Account, Computers: nothing on the machine itself is changed, but no device reaches it any more.
If remotxai lock status prints SUSPENDED next to a device, that device signed two different changes to the account history at the same point, which only a stolen or copied key does. This computer refuses everything it signs from then on. Revoke it from another device or computer that can, check with its owner, then run remotxai lock confirm-fork <device-id> on this computer and type the confirmation it asks for, so this computer accepts the revocation.
Move a computer to another organisation: remotxai logout
Section titled “Move a computer to another organisation: remotxai logout”remotxai logoutremotxai upA computer belongs to one organisation at a time. remotxai logout signs it out. remotxai up connects it to the new one. If the service can’t be reached, remotxai logout --local removes only local state.
Pair a phone: remotxai pair
Section titled “Pair a phone: remotxai pair”Pairs one phone directly with one computer. Skip it if you signed in and connected the computer with remotxai up.
New pairing is off by default. remotxai pair setup refuses, and no new phone is admitted, unless the daemon runs with REMX_LEGACY_PAIRING=1. Phones already paired keep working. A computer that holds a pairing and isn’t in an organisation says so in remotxai status and remotxai doctor.
On a computer that uses the remotxai relay, pairing has ended. Paired phones and browsers no longer connect, even with REMX_LEGACY_PAIRING=1: sign in to the app instead and the computer shows up under your organisation. Only remotxai pair list and remotxai pair revoke still run there, to clean up old entries.
| 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 default maximum). |
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. |
remotxai pair label <prefix> <name> |
Renames a phone. The audit log names the phone that approved, sent a prompt or ended a session by this name. |
Steps: Pair your phone.
Check the setup: remotxai doctor
Section titled “Check the setup: remotxai doctor”remotxai doctorPrints PASS, WARN, FAIL or SKIP per check and exits with an error if any fail. --json gives machine-readable output. It prints no keys or settings.
On a computer in an organisation, an access list row fails when the computer’s saved access list no longer opens. Teammates are refused until you delete the file the row names, and the computer then fetches the list again. The owner keeps access meanwhile. Share a computer explains access lists.
Check it is running: remotxai status
Section titled “Check it is running: remotxai status”remotxai statusPrints one line saying whether remotxai is running and linked to the relay, the number of devices and sessions, and any row that needs action. remotxai status --verbose adds the build, the relay and the plan details, and the last 20 times a phone or browser connected: how long the computer took from the connection opening to the end of its first answer, how many messages and bytes it sent, and the median and 95th percentile of each. The numbers carry no session names or content. --json gives machine-readable output.
Complete commands with Tab: remotxai completion
Section titled “Complete commands with Tab: remotxai completion”source <(remotxai completion zsh)Add that line to ~/.zshrc (after compinit) or ~/.bashrc with bash. For fish, run remotxai completion fish > ~/.config/fish/completions/remotxai.fish. The script changes nothing on its own.
Use the computer from its terminal: remotxai tui
Section titled “Use the computer from its terminal: remotxai tui”remotxai tuiremotxai tui --plainremotxai tui --no-qrremotxai tui open <session>remotxai tui --forgetSigns in to the running daemon as this computer’s terminal device and opens a full-screen view: the list of sessions, then one session with its transcript, a message box and a card for each approval or question it waits on. Replies print as formatted markdown: tables in boxes sized to the terminal, code blocks, lists, quotes and headings. Each tool call is one line, the tool name apart from what it ran, with a dot that shows whether it is still running. The background processes the session runs show above the message box with how long each has run or how it ended, and a message waiting in the queue shows there once, marked queued, until the agent takes it. NO_COLOR turns colour off. On an approval for an ordinary tool call, 1 allows it once and 2 denies it. The card shows the tool name and the whole input, wrapped. If the call is too long to show in full, or the computer didn’t send its input to the terminal, 1 does nothing and the card says to allow it in the app; 2 still denies. A card that only a person can answer (one marked human-only, one that drives remotxai itself, or one that changes the session’s mode) takes the same 1 and 2 while the presence window is open. Without a window it says Open the presence window to answer and p opens one with Touch ID; over SSH or without Touch ID it says Sign on phone. Every card shows whether the window is open and how long it has left, and each answer to such a card under the window rings the terminal bell and leaves a line saying what was answered. A mode change also says what it grants, for how long and on which session before a key works. ctrl+l locks the window, and ctrl+x drops its key at once; a second ctrl+x stops every session, which the computer takes from the terminal only while its window is open. While a window is open, a program that can type into this terminal, such as an agent in the same tmux, can answer the card on screen, so lock the window before you step away. Questions answer here too: pick an option by its number or with the arrows and space, type your own answer or a note where the question takes one, and press enter; d declines and c cancels. A form still goes to the app. The keys wait a moment after a card appears, so a key you meant for the message box doesn’t answer it. From the terminal you can send messages, interrupt a turn, take your newest queued message back with up to edit it, answer the card on screen once, answer questions, lower a session’s mode with shift+tab and undo your own message or lowering. The computer refuses everything else from it, such as a person-only card without the window or your account passkey, approving all similar calls, editing what a call runs, answering by voice, raising a mode from the message box, accepting a form, cancelling a message another device queued, changing settings, plugins or grants, adding a passkey or signing, and writes the refusal to the audit log. enter opens the highlighted session, tab goes back to the list, esc interrupts a running turn, and ctrl+c twice leaves. Without a terminal, or with --plain, it prints the session list and exits. The first run asks before it adds the terminal as an Admin device called TUI on <computer>; --yes skips the question and --label picks another name. Under an organisation lock it gets your role on this computer instead, and each sign-in lowers it again if your role there went down. The device talks to the daemon over its own socket on this computer, never through the relay, and shows up in the device list on your phone with a Terminal app tag, where you can revoke it. --forget revokes it from the terminal and deletes its key.
On a Mac, the terminal can also answer with Touch ID. ctrl+t adds this terminal’s Touch ID key. On a personal computer in your organisation it opens your browser at a page that shows the key’s fingerprint, the same one the terminal shows, and you confirm with Touch ID for your account passkey. No phone is needed, and an agent can’t do it for you. Close the page if you didn’t press ctrl+t. On any other computer you approve the key with a passkey from another device, never from the terminal. After that, a card marked human-only offers 3 to allow it once and 4 to deny it, each with a Touch ID prompt that names the request and the answer. ctrl+w opens a window with one Touch ID: for up to 5 idle minutes, and 15 at most, 1 and 2 answer ordinary cards without asking again. ctrl+g opens the same window from your phone, with a passkey or an authenticator code. A window opened with an authenticator code answers plain cards only; a person-only card needs a window opened with Touch ID or a passkey. The window ends when you press ctrl+w again, leave the terminal, lock the screen, press panic or revoke the device, and the audit log names the window on every answer it carried. Over SSH and on Linux there is no Touch ID or window. The app’s card for approving a terminal’s Touch ID key ships in a later update; until then the terminal sends these cards to your phone as before.
Without a window, 1 or 2 on a person-only card asks for your account passkey over that one answer. That covers a card marked human-only, one that drives remotxai itself, a mode change and one that reaches past the call, and works on Linux, over SSH and on a computer with no Touch ID. On a desktop session the terminal opens a confirm page in your browser. Over SSH, in tmux or screen, as root or with no browser, it prints a short address, a code and a QR code of the address with the code filled in: open it on any device signed in to your account, or scan the QR code with your phone. The page shows the request in plain words, the computer and the terminal, and asks you to confirm before it asks for the passkey. The code answers that one card and expires in 5 minutes. The QR code holds only the address and the code, and the terminal leaves it out when it’s narrower than the code; --no-qr leaves it out always. The computer checks the passkey against its own organisation lock before it takes the answer, so an agent typing into the terminal can’t approve. Grants and approving all similar calls stay refused from a terminal, and a shared computer has no owner passkey to ask for, so those cards go to your phone.
remotxai tui open <session> opens one session by its id, the start of its id or its label. It prints the last 20 turns and then everything the agent says and does as it happens, and each line you type goes to the session as your message, from this terminal device, like a message from your phone. While it is open the session shows the terminal among its viewers. ctrl+d leaves. A computer holds at most 4 of these per terminal device and 8 in all.
Answer a card from the command line: remotxai approve
Section titled “Answer a card from the command line: remotxai approve”remotxai approve <session>remotxai approve <session> <request-id>remotxai approve <session> <request-id> --denyAnswers an approval card as this computer’s terminal device, the same answer 1 or 2 sends in remotxai tui. With only a session (its id, the start of its id or its label) it lists the cards that session waits on and marks the ones only a person can answer. With a request id it allows that card once, or denies it with --deny. A person-only card asks for your account passkey the same way the terminal app does, in this computer’s browser or with an address, a code and a QR code to open on any device. --via browser or --via device picks the route and --no-qr leaves the QR code out. Run remotxai tui once first so the terminal is a device of the computer. remotxai approvals is a different command: it manages standing approvals.
Standing delegations: remotxai delegations
Section titled “Standing delegations: remotxai delegations”remotxai delegations [list] [--json]remotxai delegations revoke <id>remotxai provenance rotateremotxai provenance rotate --compromisedremotxai delegations lists what your sessions may do without asking, with each delegation’s scope, expiry, uses left and state; --json prints that list as JSON and works with list only. revoke ends one at once; <id> can be any unique start of it. remotxai provenance rotate changes the key the computer signs delegations with, and --compromised revokes the old key so nothing it signed counts. Nothing here creates a delegation: that needs an Admin phone and its passkey. Standing delegations.
Upgrade: remotxai upgrade
Section titled “Upgrade: remotxai upgrade”remotxai upgrade --checkremotxai upgrade--check reports a newer version without downloading it. remotxai upgrade installs it. It asks before restarting 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
Section titled “Switch a session’s profile: remotxai sessions switch-profile”remotxai sessionsremotxai sessions switch-profile <session-id> <profile>remotxai sessions lists session IDs. switch-profile moves a running Claude Code, Codex or Pi session to another profile of the same agent and keeps the conversation. It’s refused while a turn, approval or tool call is running.
Two limits apply. The refusal says what to do:
- 256 MiB of disk must stay free after the copy. Free space and retry.
- One message can be at most 8 MiB in Claude Code or 32 MiB in Codex and Pi. A Claude Code conversation can have at most 1 million records. Clear the conversation and switch the new one. The old one stays under the original profile.
| 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 | Stopped halfway. Check which account is running, then run remotxai sessions clear-switch-recovery <session-id>. |
More: Profiles and accounts.