Skip to main content
The @phoneuse/cli npm package installs the phoneuse command. See installation for the release target, availability check, login and optional source instructions. The CLI is a thin client over the same control plane the agent surface uses, with 20 commands. The same program also runs from an existing checkout: corepack pnpm cli <command> during development, or node dist/cli/main.js <command> after corepack pnpm build. See installation for the details. Bad input never crashes the CLI: it prints the usage block and exits 2, and that includes a flag used on a command that does not read it. phoneuse --help lists every command; phoneuse <command> --help prints that one command’s arguments, flags and an example. Both come from the same table this page is generated from, so the terminal and this page cannot disagree.

Commands

Global options

These apply wherever they make sense rather than to one command. Authentication: run phoneuse login once and the CLI stores an API key for that --server in the system keychain, or a private credentials file when a keychain is unavailable. PHONEUSE_API_KEY overrides the stored key, which is what CI and scripts use; PHONEUSE_DEV_TOKEN is sent only to a control plane on your own machine (a loopback --server).

phoneuse apps

Inspect phone app inventory, refresh it, and recover an original request. To install an app, use the Apps page in the Console (https://console.phoneuse.com/apps).
phoneuse apps library capabilities
phoneuse apps library check
phoneuse apps library refresh
phoneuse apps library refresh-status
phoneuse apps library refresh-results
phoneuse apps library request

phoneuse login

Log in from this terminal: approve the request in the console and the CLI stores a new API key for your organization in the system keychain. Run it again whenever you need a new key.

phoneuse whoami

Show the organization, key id, scopes and expiry of the key this CLI sends, and where that key came from.

phoneuse logout

Revoke the key phoneuse login stored and remove it from this machine. A key in PHONEUSE_API_KEY is left alone. Keys can also be deleted on the console’s Keys page.
Takes no arguments or options.

phoneuse devices

List every device your org can see, with its status and capabilities.

phoneuse acquire

Claim exclusive use of a device and print the lease it returns.

phoneuse renew

Push a lease’s expiry back before it runs out, keeping the same lease id. A lease that expires mid-session strands whatever you were doing, so renew it rather than acquiring again.

phoneuse release

Give a device back by the lease id acquire returned.

phoneuse tap

Tap one point on a device.

phoneuse swipe

Drag from one point to another on a device: scroll a list, pull a sheet down, page sideways.

phoneuse long-press

Press and hold one point on a device, for the context menus and drag handles a tap never opens.

phoneuse type

Type text into whatever input the device has focused. Focus it first: this types, it does not aim.

phoneuse key

Press one of the phone’s own keys on a device: home, back, enter, delete, app_switch, power, volume_up, volume_down.

phoneuse open

Launch an app on a device by its OS-level id, instead of tapping through a home screen to find it.

phoneuse screenshot

Capture a device’s screen and write the image to a file.

phoneuse ui

Print the device’s UI tree, the text-and-elements view a screenshot cannot give you. The tree goes to stdout and its metadata to stderr, so redirecting the output leaves a clean file. Cloud phones do not provide a UI tree; use screenshot there.

phoneuse doctor

Check this machine: node version, the credential in use and control-plane reachability.
Takes no arguments or options.

phoneuse mcp

Give a stdio-only MCP client (Claude Desktop, Cursor) your cloud phones: it relays to the hosted MCP with the key phoneuse login stored.

phoneuse run

Start an agent run on a device for one natural-language goal. PhoneUse drives it for you; with —executor self_hosted nothing happens on the device until your own worker connects to the run’s VisualRemote base url.

phoneuse runs

Check, continue or stop a run by its id. A run that stops at needs_user_control waits for a person: do what it asks on the phone, then resume it, or cancel it to free the phone for another run.
phoneuse runs show
phoneuse runs resume
phoneuse runs cancel