@phoneuse/cli@0.6.0, the current release
on npm, and run the phoneuse command. Node 22 or newer is required. The
REST API example and
MCP quickstart are also available.
What this repository’s CI runs today
On every pull request and on pushes to the trunk, CI checks the source, regenerates the documentation and verifies that generated files match. Its CLI checks include:-
The docs regenerate and the tree must not move.
gen:docsrebuilds the reference pages from the code, andgit diff --exit-codefails if that produced any change. A tool, scope, error code, route or CLI command that changed without a regeneration turns this red. It is the only thing stopping these pages from quietly describing an older surface. -
The staged CLI is executed through its installed binary.
check:packed-cliinstalls the staged package into a temporary directory and checks that its binary produces output. This catches a broken package entry point that running the source alone would miss. It does not control a real device or prove a customer’s installation works. -
An end to end script exercises the whole sequence.
corepack pnpm e2e:clistarts a control plane and a stand in device, then runs the full sequence from registering a row through acquiring, observing, acting and releasing, plus the negative cases. It is run on demand rather than on every commit.
Using the CLI in your own pipeline
Nothing above stops you from running it. These are the constraints that actually apply.Install the npm package
Pin the package version so your runner uses the release you tested:Optional: run from a checkout
If your runner has authorized access to the private repository, use a reviewed repository revision, install its locked dependencies and run the source entry point:corepack pnpm cli for phoneuse in the
examples below.
Authenticate from the environment
A runner has nobody to approvephoneuse login, so put an API key in a
secret and export it. PHONEUSE_API_KEY takes precedence over any key a
login stored, and the CLI never reads a credential from a flag, so a key cannot
leak into a command line that a build log echoes.
https://mcp.phoneuse.com, is the default; pass
--server <url>, or set PHONEUSE_SERVER, for any other.
The server must be https unless it is loopback. Sending a credential in the
clear to a remote host is refused rather than warned about.
Give the key only what the job needs
Issue a separate key per pipeline, scoped to what that pipeline does and, if the job only ever touches one device, narrowed to that device. A key restricted to a subset cannot see the rest of the fleet, so a mistake in a script cannot reach a device the job was never meant to touch. See Authentication.Release what you acquire
A lease is exclusive, and a job that exits without releasing blocks the next one until the lease expires on its own. Release in whatever your runner calls a cleanup step, not on the happy path.Parse the machine readable output
Use--json for anything a script reads. It prints the structured result the
tool returned, whose shape is published in the
tool reference. The default human summary is written for a
person and is free to change.
Expect to queue
A device holds one lease at a time, so a job may wait for a device rather than getting one immediately. Build for that: fail the step with a clear message rather than retrying an acquire in a tight loop.Watch a run to completion
If your job hands a goal to the agent tier rather than driving each step,run returns a run id immediately. Pass --watch to poll until the run
reaches a terminal state, and the exit code follows the outcome.
--executor phoneuse in CI to let PhoneUse drive the run. An API key’s
default executor is
self_hosted, which needs your own worker and a worker URL that a CI log must
not hold. --watch --json refuses an explicit self_hosted run before
starting it. If the server’s default makes a run self_hosted, the CLI tries
to cancel it and exits 2. If cancellation fails, it names the run so you can
cancel it through the API.
--max-steps can only lower the budget. The control plane’s own ceiling
cannot be raised from a client. See Runs.