Skip to main content
phonebase is a command line client for the 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. It installs from npm as phonebase, and phonebase login is the first thing to run: it pairs the terminal with your console session and stores an API key for your organization. See Installation.
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

Every command talks to a control plane over HTTP. By default that is the hosted one, https://mcp.phonebase.co; --server <url> points it somewhere else, such as a control plane on your own machine, and PHONEBASE_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:
  • PHONEBASE_API_KEY from the environment, for CI and scripts.
  • The key phonebase login stored for that server.
  • PHONEBASE_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. phonebase 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.
phonebase 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 phonebase 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.

​
Getting it

See Installation for logging in and for running it from a checkout instead, and CLI in CI for what the repository’s own automation does with it today.