Skip to main content
This page has two halves. The first states what our own pipeline runs today, so you can see the CLI used in a real one. The second is guidance for putting it into yours. The pipeline examples below target @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 workflow also runs contract, database and integration checks. For the CLI, these steps establish the following:
  • The docs regenerate and the tree must not move. gen:docs rebuilds the reference pages from the code, and git diff --exit-code fails 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-cli installs 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:cli starts 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.
Documentation publishing is a separate workflow. It is decoupled from this one on purpose, so that fixing a typo does not rebuild the application. Releasing the CLI to npm is a third workflow, and it is manual: someone dispatches it, and it publishes the version currently written into the source. It runs the typecheck, the unit tests, the build and the packed CLI check, and it refuses a version that is already on the registry. The first scoped release used the owner’s authenticated npm session. npm now trusts this repository and this workflow as the package’s publisher, so later releases publish from the workflow without a personal npm login. Each workflow dispatch remains a separate release decision.

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:
From that checkout, substitute corepack pnpm cli for phoneuse in the examples below.

Authenticate from the environment

A runner has nobody to approve phoneuse 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.
The hosted control plane, 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.
Releasing a device you no longer hold is a no operation, so the trap is safe even when the lease already expired.

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.
Name --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.

Do not run two control planes over one device set

Worth stating because CI is where it happens. Two control plane processes over the same devices would each keep their own view of who holds a lease and could hand the same physical device to two callers. The receipt ledger is locked by a single process, so the second one refuses to start rather than racing the first. If a job needs its own control plane, give it its own devices, or its own ledger path.