> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phoneuse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> An operator client over the same control plane, with no behaviour of its own.

`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](/cli/installation).

```bash theme={null}
npm install -g phonebase
phonebase login
phonebase devices
```

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.

<Card title="Command reference" href="/cli/commands" icon="terminal">
  Every command, its arguments, and its flags, generated from the parser
  itself.
</Card>

## What it is for

| You want to | Use |
| - | - |
| Log in, check which key you are using, or log out | `login`, `whoami`, `logout` |
| Register a device the control plane should know about | `rows` |
| Check your environment before looking further | `doctor` |
| See what the control plane can reach | `devices` |
| Drive a device by hand | `acquire`, `screenshot`, `tap`, `release` |
| Hand a device to an autonomous run | `run` |
| Serve MCP over stdio to a client that spawns processes | `mcp --stdio` |

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

```bash theme={null}
phonebase devices
phonebase devices --server http://127.0.0.1:8788
```

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.

<Warning>
  The CLI refuses to send a credential in the clear to a non loopback server.
  A remote `--server` has to be `https`.
</Warning>

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

```bash theme={null}
phonebase tap black-arm-01 500 500
phonebase screenshot black-arm-01 -o shot.jpg
phonebase acquire black-arm-01 --json
phonebase release black-arm-01 <leaseId>
```

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](/mcp/reference).

```bash theme={null}
phonebase acquire black-arm-01 --json
```

## Getting it

```bash theme={null}
npm install -g phonebase
```

See [Installation](/cli/installation) for logging in and for running it from a
checkout instead, and [CLI in CI](/cli/ci-cd) for what the
repository's own automation does with it today.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.