Installing the CLI

Everything on PocketBase Cloud can be done two ways: in the portal, or from your terminal with the pb 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.

Install

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

npm (global)

npm i -g @pocketbasecloud/cli
pb --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). Override the destination with PB_INSTALL_DIR.

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 pb ./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

pb cloud login    # opens your browser
pb cloud whoami   # ada@example.com — plan: Pro

login opens the portal, waits for you to authorize, and stores the token in ~/.config/pb/config.json (or $XDG_CONFIG_HOME/pb/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

pb cloud project create my-app   # create a project
pb cloud project use my-app      # make it the default for this machine
cd db && pb cloud pb 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 pb.json file in that directory, so from then on a bare pb cloud pb deploy in the same place redeploys it.

One deploy command for all three

You don’t have to tell the CLI which kind of thing you’re deploying. pb cloud 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 && pb cloud deploy --name my-app-db

Detected a PocketBase instance (pb_hooks/) — running `pb cloud pb 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:

pb cloud deploy backend        # deploy as a backend, whatever is in here
pb cloud 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.

Linking a directory to a resource

Give each PocketBase, frontend, or backend its own directory and link it once. Afterwards deploy, info, rm, logs, and env need no --name/--id when run there:

cd frontend
pb cloud link frontend web   # bind ./ to the frontend named "web"
pb cloud frontend deploy     # no flags — redeploys the bound frontend
pb cloud frontend info
pb cloud unlink              # detach; the cloud resource is untouched

pb cloud link never creates or changes anything in the cloud — it only writes the binding. Deploying records it too, so the first deploy of a new resource links the directory for you.

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

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

Commit pb.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:

pb cloud frontend deploy                                   # production
pb cloud frontend deploy --env staging                     # staging
pb cloud frontend deploy --env staging --name web-staging  # creates it
PB_ENV=staging pb cloud frontend deploy                    # for a whole shell

--env works the same on info, rm, logs, and env. pb cloud environments lists what the directory targets, and pb cloud unlink --env staging forgets one (--all forgets them all).

Global flags

Run pb --help for the full command list, or pb <command> --help for one command. pb --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 PB_TOKEN=…    # a PocketBase Cloud user token

pb cloud whoami --json                       # preflight
pb cloud frontend deploy --no-input --json   # never prompts

PB_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, pb administers any PocketBase — cloud-hosted, self-hosted, or the one running on your laptop:

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

See Managing Your Instance for the full set.

Next steps

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