Install from npm
These instructions target version0.6.0 of
@phoneuse/cli, the current
release on npm. The package requires Node 22 or newer and installs the
phoneuse command:
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 hasdevices:read:
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.
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
Whatphoneuse 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.
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,doctorreports a failure with the fix.
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.
cli is passed through, so flags work as documented:
Running the built entry point
Building compiles the repository intodist.
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.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.
/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.