Installing the CLI

Everything on PocketBase Cloud can be done two ways: in the portal, or from your terminal with the pbc CLI. The portal is the fastest way to see what you have; the CLI is the fastest way to change it, and the only one that works in CI.

Every guide in these docs shows both paths, so you can pick per task — they act on the same account and the same resources.

Renamed in 0.6.0: pb is now pbc — the command, the project file (pb.json → pbc.json), the variables (PB_TOKEN → PBC_TOKEN, and so on), and the saved login (~/.config/pb/ → ~/.config/pbc/). Every old name still works, so nothing you already scripted has to change: pb runs the same binary, a directory holding a pb.json keeps using it, a PB_* variable is read when its PBC_* twin is unset, and your login is carried over the first time the CLI saves. The one manual step is a repository secret — new workflows read secrets.PBC_TOKEN.

Install

Pick whichever fits your setup. The npm and curl | sh channels are fully independent.

npm (global)

npm i -g @pocketbasecloud/cli
pbc --help

npx (no install)

npx @pocketbasecloud/cli --help

curl | sh (macOS/Linux, no Node required)

curl -fsSL https://raw.githubusercontent.com/pocketbasecloud/cli/main/scripts/install.sh | sh

Downloads the binary from the latest GitHub release, verifies its SHA-256, and installs it to /usr/local/bin (or ~/.local/bin), with pb linked beside it. Override the destination with PBC_INSTALL_DIR (PB_INSTALL_DIR still works).

From source (Deno) — for platforms with no prebuilt binary:

git clone https://github.com/pocketbasecloud/cli
cd cli
deno install -g -A -c deno.json -n pbc ./main.ts

Prebuilt binaries cover macOS (arm64, x64), Linux (arm64, x64), and Windows (x64; Windows-on-ARM runs the x64 build under emulation).

Log in

pbc login    # opens your browser
pbc whoami   # [email protected] — plan: Pro

login opens the portal, waits for you to authorize, and stores the token in ~/.config/pbc/config.json (or $XDG_CONFIG_HOME/pbc/config.json). Nothing else needs configuring — the CLI always talks to PocketBase Cloud’s own hosts.

If you don’t have an account yet, see Creating a Project — signup and choosing a plan happen in the portal.

Your first deployment

pbc project create my-app   # create a project
pbc project use my-app      # make it the default for this machine
cd db && pbc pocketbase deploy --name my-app-db

deploy packages the directory, ships it, waits for the resource to come up, and prints the URL and the generated superuser login. It also records the resource in a pbc.json file in that directory, so from then on a bare pbc pocketbase deploy in the same place redeploys it.

If you just want the database and have no files to ship yet, there is nothing to be in a directory for:

pbc pocketbase create my-app-db

create provisions an empty instance and stops there — nothing is built, packaged, or uploaded. It still records the instance in the directory’s pbc.json, so a later pbc pocketbase deploy here needs no --name. (pbc pocketbase deploy also creates an empty instance when the directory holds no pb_public, pb_hooks or pb_migrations.)

One deploy command for all three

You don’t have to tell the CLI which kind of thing you’re deploying. pbc deploy looks at the directory, works out whether it holds a PocketBase instance, a static site, or a backend, and runs that kind’s deploy:

cd db && pbc deploy --name my-app-db

Detected a PocketBase instance (pb_hooks/) — running `pbc pocketbase deploy`.

It is the same deploy either way — the same flags, the same steps, the same output. Only the choice is automatic, and the line above shows what was chosen and which file decided it.

The answer comes from the first of these that applies:

Rule 1 is the important one: a directory that has already been deployed is never re-guessed, so adding a deno.json to a deployed frontend cannot start deploying a backend over it.

Naming a kind overrides the detection, which is also how you deploy a directory that matches none of the rules:

pbc deploy backend        # deploy as a backend, whatever is in here
pbc deploy frontend web   # …and call the new resource "web"

When nothing in the directory points either way, the CLI asks. With --no-input or --json — a CI run — it fails instead, naming the three explicit commands.

Binding a directory to a resource

Give each PocketBase, frontend, or backend its own directory. The first deploy of a new resource records the binding in pbc.json, and afterwards deploy, info, rm, logs, and env need no --name/--id when run there:

cd frontend
pbc frontend deploy --name web   # creates "web" and records the binding
pbc frontend deploy              # no flags — redeploys the bound frontend
pbc frontend info

There is no separate link command — the file is the link. To point a directory at a different resource, or to detach it, edit pbc.json; nothing in the cloud is touched either way.

The binding lives in pbc.json next to your code. Each file carries its own projectId, so directories stay independent, and any pbc command run underneath one resolves to that project automatically:

// frontend/pbc.json
{
  "projectId": "dhs4xnprgplurvo",
  "kind": "frontends",
  "defaultEnvironment": "production",
  "environments": {
    "production": { "id": "…", "name": "web" }
  },
  "build": { "command": "npm run build", "outputDir": "dist" }
}

Commit pbc.json — it is how your teammates and your CI deploy the same resource without passing flags.

Multiple environments

One directory can deploy to several environments — staging and production, say. Each is a separate cloud resource in the same project:

{
  "projectId": "dhs4xnprgplurvo",
  "kind": "frontends",
  "build": { "command": "npm run build", "outputDir": "dist" },
  "defaultEnvironment": "production",
  "environments": {
    "production": { "id": "…", "name": "web" },
    "staging": {
      "id": "…",
      "name": "web-staging",
      "build": { "command": "npm run build:staging" }
    }
  }
}

Pick one with --env; without it, commands use defaultEnvironment:

pbc frontend deploy                                   # production
pbc frontend deploy --env staging                     # staging
pbc frontend deploy --env staging --name web-staging  # creates it
PBC_ENV=staging pbc frontend deploy                    # for a whole shell

--env works the same on info, rm, logs, and env. pbc environments lists what the directory targets; remove an entry from the environments block in pbc.json to forget one.

Global flags

Run pbc --help for the full command list, or pbc <command> --help for one command. pbc --help --json prints the whole command manifest — useful when driving the CLI from a script or an AI agent.

Running in CI

Authenticate with a token instead of a browser login, and make every command fail rather than ask:

export PBC_TOKEN=…    # a PocketBase Cloud user token

pbc whoami --json                       # preflight
pbc frontend deploy --no-input --json   # never prompts

PBC_TOKEN is all a CI job needs to set. Errors are printed as {"error":"…"} on stderr with a non-zero exit code:

Working with any PocketBase instance

Beyond the cloud commands, pbc administers any PocketBase — cloud-hosted, self-hosted, or the one running on your laptop:

pbc admin use https://my-instance.pocketbasecloud.com   # select an instance
pbc admin login                                        # log in as superuser
pbc admin collections ls
pbc admin records ls posts
pbc admin settings backup create

See Managing Your Instance for the full set.

Next steps

• Create a project
• Develop locally with PocketBase
• Deploy a PocketBase instance