Skip to main content
These instructions target version 0.6.0 of @phoneuse/cli, the current release on npm. It installs the phoneuse command and requires Node 22 or newer. phoneuse is a command line client for the PhoneUse control plane. It is useful for setting a device up, checking that one works, and driving one by hand while you are debugging something an agent did. phoneuse login pairs the terminal with your console session and stores an API key for your organization. See Installation for prerequisites, optional source instructions and a REST API alternative.
It is deliberately thin. Every device command it offers is a call to the same /mcp endpoint an agent uses, and it holds no device logic of its own. That has a practical consequence worth knowing: if a command works in the CLI but not from your agent, the difference is in your client or your credential, not in the control plane.

Command reference

Every command, its arguments, and its flags, generated from the parser itself.

What it is for

Talking to a control plane

Device commands talk to a control plane over HTTP. By default that is the hosted one, https://mcp.phoneuse.com; --server <url> points it somewhere else, such as a control plane on your own machine, and PHONEUSE_SERVER sets the same thing for a whole shell.
Credentials never come from a flag, so they do not land in your shell history or in a process listing. The CLI sends the first of:
  • PHONEUSE_API_KEY from the environment, for CI and scripts.
  • The key phoneuse login stored for that server.
  • PHONEUSE_DEV_TOKEN, for a control plane on your own machine. It is never sent to a server that is not loopback.
Whichever it is goes as a bearer token through the same authentication pipeline every other caller uses. phoneuse whoami tells you which one.
The CLI refuses to send a credential in the clear to a non loopback server. A remote --server has to be https.
phoneuse login does not hold an OAuth session. It mints an ordinary API key through a console approval, so everything that is true of API keys is true of it: it has scopes and an expiry, it shows on the console’s /keys screen, and you can delete it there. When you need a new one, run phoneuse login again.

You do not have to carry a lease

--lease is optional, for the same reason leaseId is optional in the tool schemas: your key already says which organization you are, and a device your organization holds is one you may act on. A gesture on a device your organization does not hold takes it for you, and the lease expires on its own ten minutes after the last renewal. release is the one command that needs the id, so take it explicitly when you want to give the device back early.
Coordinates are on the same normalized grid the tools use: both axes run 0 to 1000 whatever the real screen size is.

Human output and machine output

By default a command prints a short human summary. Pass --json and it prints the structuredContent the tool returned, unmodified. Use --json in anything you script. The summary is written for a person and is free to change; the structured shape is published in the tool reference.

Release status

The current release is @phoneuse/cli@0.6.0, published on npm on 2026-10-22. See the changelog for what changed. See Installation for setup and CLI in CI for pipeline instructions. From an authorized repository checkout, corepack pnpm cli runs the program from source.