# The Playcode CLI

> The playcode command - sign in through the browser, list projects, read files and run commands on a project's computer, publish, and call any operation.
> Source: https://playcode.io/docs/developers/cli - last reviewed 2026-10-10.

`playcode` is Playcode's command line. Sign in once through the browser, and every command acts as you, with the permissions you allowed. It is also the door a coding agent such as Claude Code walks through: it runs shell commands, so it needs nothing more.

## Install

| Way | Command |
|---|---|
| Install it | `npm i -g @playcode/cli` |
| Run it once without installing | `npx @playcode/cli <command>` |
| Check the version | `playcode --version` |
| List the commands | `playcode --help` |

## Sign in

| Command | What it does |
|---|---|
| `playcode login` | Shows a page address and a code. Open the page, type the code, choose **Continue** and **Yes, sign in**, then pick a workspace and choose **Allow**. The code expires after 10 minutes |
| `playcode login --permissions projects:vm,domains:write` | The same, asking for more. Without it, the sign-in asks for `projects:vm` only |
| `playcode login --paste` | Asks for an access token instead of the browser. `playcode login pc_live_...` takes it on the line |
| `playcode whoami` | Says how you are signed in, and whether the sign-in reaches your projects |
| `playcode logout` | Deletes the stored sign-in. A browser sign-in is also taken back at Playcode |

A browser sign-in refreshes itself while you use it. It ends after 30 days without use, and after a year at the latest. It is stored in `~/.config/playcode/credentials.json`, readable only by you. To sign it out from elsewhere, choose **Revoke** beside it under **Signed in as you** on the **Developers** page.

## Commands

A project is named by its uid or by the name it answers to, as `playcode projects` shows them.

| Command | What it does |
|---|---|
| `playcode projects` | Your projects: title, name, kind and uid |
| `playcode vm ls <project> [path]` | Lists a project's files. `--depth N` goes deeper |
| `playcode vm cat <project> <path>` | Prints one file |
| `playcode vm exec <project> -- <shell line>` | Runs one shell line on a Cloud app's computer, prints its output as it runs, and exits with its exit code. Quote the line as for ssh |
| `playcode vm cp <local> <project>:<path>` | Uploads a file or a folder to a Cloud app's computer |
| `playcode vm cp <project>:<path> <local>` | Downloads a file or a folder |
| `playcode vm shell <project>` | Opens an interactive shell on a Cloud app's computer. It needs a terminal |
| `playcode publish <project>` | Starts a publish of a Cloud app and returns at once |
| `playcode publish <project> --wait` | Publishes and waits until the publish ends: exit code 0 when it is live, 1 when it failed |
| `playcode mcp` | Runs an MCP server on stdio over your sign-in. See [Connect Claude Code, Cursor or another MCP client](/docs/developers/mcp) |
| `playcode <family>` | Lists a family's operations, each with its effect and whether it needs consent |
| `playcode <family> <operation> --help` | Prints an operation's arguments |
| `playcode <family> <operation> --<argument> <value>` | Calls the operation |

Example: `playcode domains domainGet --domain example.com`.

An argument value is read as JSON when it parses, as a plain string otherwise; `@file.json` reads it from a file. An operation that needs consent takes `--proposalId` from `proposalCreate`: see [Consent](/docs/developers/api#consent).

## Flags

| Flag | Works with | What it does |
|---|---|---|
| `--json` | Every command | Answers with JSON on stdout, for a program to read |
| `--env DEV` or `--env PROD` | `vm` commands | Which computer: development (the default) or production |
| `--depth N` | `vm ls` | How many folder levels to list; 1 by default |
| `--cwd DIR` | `vm exec` | The folder the command runs in |
| `--timeout 10m` | `vm exec` | Stops the command after this long: `90s`, `10m` or `2h`. 15 minutes by default, 60 minutes at most |
| `--alias NAME` | `publish` | The address name for the published app, like `coolapp` |
| `--wait` | `publish` | Waits until the publish ends |
| `--permissions A,B` | `login` | The permissions the browser sign-in asks for |
| `--paste` | `login` | Signs in with an access token |
| `--token TOKEN` | Every command | Uses this access token for one command |
| `--origin URL` | Every command | The Playcode address; `https://playcode.io` by default |

## Environment variables

| Variable | What it does |
|---|---|
| `PLAYCODE_TOKEN` | An access token. It wins over the stored sign-in: use it in CI and scripts |
| `PLAYCODE_ORIGIN` | The Playcode address, like `--origin` |
| `PLAYCODE_CONFIG_DIR` | Where to keep the stored sign-in, instead of `~/.config` |

## Exit codes

| Code | Means |
|---|---|
| 0 | Done |
| 1 | The call failed, or a publish with `--wait` failed |
| 2 | A usage mistake, or not signed in, or the sign-in ended |
| 3 | Playcode could not be reached, or answered something unexpected |
| 4 | Not allowed: a missing permission, no access, or consent needed |
| 5 | Not found |
| 124 | `vm exec`: the command ran out of time |
| 130 | `vm exec`: the command was cancelled |

For `vm exec`, any other code is the command's own exit code.

## Operation families

| Family | What it holds | Permission it needs |
|---|---|---|
| `projects` | Projects, their files, commands, publishes | `projects:read` to read; `projects:vm` to change |
| `domains` | Names to buy, domains, DNS zones, orders | `domains:read` to read; `domains:write` to change |
| `events` | The workspace's activity | None |
| `consent` | Proposals for operations that need consent | None |
| `api` | Search and describe operations | None |
| `apps`, `tokens`, `webhooks` | App settings, access tokens, webhook endpoints | Listed, but refused for any sign-in or token: manage these in the app |

## Limits

- `vm exec`, `vm cp`, `vm shell` and `publish` work on Cloud apps only. `vm ls` and `vm cat` work on every project.
- The first publish of a project creates its production computer, which uses credits while it runs. See [Run a Cloud app](/docs/publish/cloud-apps).
- `playcode projects` lists the projects you own, not every project you can open.
- The CLI's list of operations is fixed when the version is released; a newer operation needs a newer CLI. `playcode mcp` reads the current list from Playcode.
- A sign-in acts in one workspace. To work in another one, sign in again.