Skip to main content

Install from npm

These instructions target version 0.6.0 of @phoneuse/cli, the current release on npm. The package requires Node 22 or newer and installs the phoneuse command:
The version command should print the version on the install line. CLI 0.5.0 and later accept API keys that start with pbk_ or puk_; the older 0.4.1 accepts only pbk_.

Use PhoneUse now

You can sign in at console.phoneuse.com and work in your organization without installing the CLI. For an integration, follow the MCP quickstart or use the REST API with an existing API key that has devices:read:
Set PHONEUSE_API_KEY to your key through your normal secret store. If you need a key, follow Getting a key. This request lists the devices your key can see; it does not acquire a lease or drive a device.

Log in

After installation, run:
phoneuse login prints a link and a short code and opens your browser. Sign in to the console, check that the page shows the same code, and approve. The terminal then prints the organization you logged in to, the id of the key it received and when that key expires. No browser on this machine, or connected over SSH? Open the link on any other device where you are signed in; the terminal waits until the printed code expires.
For a run that PhoneUse drives, pass --executor phoneuse. A self_hosted run needs your own worker; scripts should pass --executor phoneuse with --watch --json. See CLI in CI for handling runs in scripts and the changelog for release history.
Running the CLI gives you the client, not access. phoneuse login needs a console account in an organization. Create one yourself at console.phoneuse.com/sign-up; your organization is created during sign-up. Nothing on this surface requires the CLI, so if you are integrating rather than operating, start at Quickstart and treat this page as optional.

Logging in

What phoneuse login gives you is an ordinary API key for your organization, the same kind the console’s /keys screen mints, named after this computer so you can find it there. It is stored in the system keychain: the macOS Keychain, or the Secret Service through secret-tool on Linux. Where neither is available it goes to ~/.config/phoneuse/credentials.json, readable only by you. The CLI never prints it.
Need a new key, say after it expired or on a new machine? Run phoneuse login again. You can also delete any key from the console’s Keys page; logout does both halves for the key this machine holds, and if the server cannot be reached it still forgets the key here and tells you it is still live, so you can delete it in the console. Already have a key? phoneuse login --with-key < key.txt checks it with the server and stores it without the browser step.

Prerequisites

  • Node 22 or newer. The package declares engines: { "node": ">=22" }. On an older runtime, doctor reports a failure with the fix.
The source instructions below are optional and require access to the private repository and an existing checkout.

Running from source

pnpm cli runs the CLI straight from TypeScript with no build step. This is the right mode while you are working on the repository, because an edit takes effect on the next command.
Everything after cli is passed through, so flags work as documented:

Running the built entry point

Building compiles the repository into dist.
dist/cli/main.js is the same entry point the release package includes: inside the package it sits at cli/main.js, which is what the manifest declares as the phoneuse binary. Both entry points use the same parser, client and control plane.

Configuring it

Two things. Which control plane. Defaults to the hosted one, https://mcp.phoneuse.com. A control plane running on your own machine is --server http://127.0.0.1:8788; to make that the default for a shell, set PHONEUSE_SERVER=http://127.0.0.1:8788. A --server flag always beats the variable. Each server keeps its own login, so logging in to a local one does not replace your hosted key. Which credential. In order: PHONEUSE_API_KEY from the environment, then the key phoneuse login stored for that server, then PHONEUSE_DEV_TOKEN (a local control plane’s dev token). The dev token is only ever sent to a loopback server: aimed at any other, the command refuses rather than send it. Use the variable in CI and scripts, where nobody is there to approve a login:
phoneuse whoami names which of the three it is using. Stored credentials keep their existing keychain identity and file path. Set PHONEUSE_CONFIG_DIR to choose another credentials directory.
From a checkout, corepack pnpm cli substitutes for phoneuse in every command below. It is the same program either way.
Sending a credential in the clear to a non loopback server is refused. Remote authenticated calls require https; a local loopback server can use http.

Checking the install

doctor runs the checks that catch the setup problems people actually hit, and exits non zero if any of them fail.
It reports on your Node version, whether the control plane answers on /healthz, and whether the credential in use is accepted and where it came from. Each failing check prints its own fix. Start there before anything else.