CLI Cookbook

Eleven recipes you can paste into a terminal. Each states its prerequisites up front and links to the full guide. If this page and pbc --help disagree, the CLI wins — pbc --help --json is the authoritative command list for your installed version.

Renamed in 0.6.0: pb is now pbc. Old names still work (pb, pb.json, PB_*, ~/.config/pb/), but write pbc in anything new. See Installing the CLI.

1. Install and discover commands

When: any fresh machine, before anything else.

npm i -g @pocketbasecloud/cli
pbc --help              # every command, grouped by scope
pbc <command> --help    # flags for one command
pbc --help --json       # full manifest as JSON — parse this, don't guess flags

No Node? curl -fsSL https://raw.githubusercontent.com/pocketbasecloud/cli/main/scripts/install.sh | sh. Full options in Installing the CLI.

2. Log in and script safely

When: before any deploy; always in CI.

pbc login     # browser auth, once per machine
pbc whoami    # check who you are

export PBC_TOKEN=…                  # CI instead of browser login
pbc whoami --json                   # preflight
pbc frontend deploy --no-input --json   # never prompts; errors as {"error":"…"} on stderr

Flag	Effect
`--json`	Machine-readable stdout; build output goes to stderr
`--no-input`	Fail instead of prompting
`--yes`, `-y`	Answer destructive confirmations with yes

Exit codes: 2 usage, 3 not permitted (plan limit), 4 not authenticated, 5 timed out, 6 failed state, 7 your build failed.

3. Ship a static site from a ZIP

When: the bundle is already built, or you deploy from the portal’s ZIP flow. Prereqs: pbc login; a dist/ (or build/) folder with index.html.

cd web
npm run build
pbc frontend deploy --name web --skip-build   # package dist/ as-is, no rebuild
# or upload an archive you built yourself:
pbc frontend deploy --name web --zip site.zip
# from now on:
pbc frontend deploy

--zip uploads your archive instead of building. First deploy records the binding in web/pbc.json — commit it so teammates and CI need no flags. Full guide: Deploying a Frontend.

4. Ship a Next.js standalone backend

When: a Next.js app with server rendering. Requires Pro. Prereqs: pbc login; next.config.* without output: "export".

cd api
pbc backend deploy --name my-app-api --runtime nextjs
# from now on:
pbc backend deploy

The CLI adds output: "standalone" to next.config.* for you (and says so), builds locally, and ships .next/standalone + .next/static + public started with node server.js. A config with output: "export" is a static site — deploy it with pbc frontend deploy instead. Your app must listen on process.env.PORT. Full guide: Deploying a Backend.

5. Attach a custom domain (with Cloudflare)

When: serve a frontend, backend, or instance from your own domain. Requires Starter or Pro.

pbc frontend domain add app.example.com --name web
# DNS at your provider:
#   subdomain → CNAME  app  →  <id>.pocketbasecloud.com
#   root      → A      @    →  the server IP shown in the portal
# Cloudflare orange-cloud (proxied)? add instead:
#   TXT  _pbc-verify  →  <instance-id>
pbc frontend domain verify app.example.com --name web
pbc frontend domain remove app.example.com --name web   # release the name

Swap frontend for backend or pocketbase for those kinds. Until verified, a deploy prints (custom domain — pending) — that is why the domain shows nothing. Full guide: Custom Domains.

6. Deploy from CI on every push

When: GitHub Actions should repeat your local deploy. Prereqs: one local deploy first, so pbc.json records project + name.

# once, locally:
pbc frontend deploy --name web
git add pbc.json && git commit -m "Link this folder to PocketBase Cloud"
pbc ci init   # writes .github/workflows/deploy.yml

# portal → Account → CLI access token → Copy, then repo:
# Settings → Secrets and variables → Actions → New secret: PBC_TOKEN
git add .github/workflows/deploy.yml && git push

Every push to the branch now deploys; the URL lands in the job summary. Never paste the token into the workflow file, and never hand-roll pbc pocketbase deploy --json in CI — the official action masks the generated superuser password for you. Full guide: Deploying from GitHub Actions.

7. Push hooks without a full redeploy

When: pb_hooks/ changed and nothing else needs shipping. Prereqs: pbc login; a directory linked to the instance (or --name).

cd db
pbc pocketbase hooks push ./pb_hooks --name my-app-db
pbc pocketbase hooks ls --name my-app-db
pbc pocketbase hooks rm old.pb.js --name my-app-db

Only flat .js/.json files directly inside the directory travel — subdirectories are skipped and named. Only *.pb.js executes; plain .js rides along so require() resolves. A full pbc pocketbase deploy from the same directory ships hooks too (plus pb_migrations merged, pb_public replaced). Full guide: Extending with Hooks.

8. Back up, download, restore

When: before anything destructive; to move an instance wholesale. Prereqs: instance superuser — pbc admin use <url> + pbc admin login.

pbc admin use https://my-app-db.pocketbasecloud.com
pbc admin login
pbc admin settings backup create pre_migration
pbc admin settings backup ls
pbc admin settings backup download <key-from-ls> --out ./backup.zip

The ZIP is the whole pb_data — schema, records, files. Restore (and upload of a foreign ZIP) lives in the instance admin panel → Settings → Backups, not in the CLI; a restore restarts the instance. Seed a new instance from a ZIP with pbc pocketbase create restored-db --backup backup.zip. Full guide: Managing Your Instance.

9. Copy schema from dev to prod

When: staging works and production should match it. Prereqs: superuser login on both instances.

pbc admin use http://127.0.0.1:8090 && pbc admin login
pbc admin collections export --out schema.json

pbc admin use https://my-app-db.pocketbasecloud.com && pbc admin login
pbc admin collections import schema.json
# wholesale replace (drops collections the file omits — asks first):
pbc admin collections import schema.json --delete-missing

With relations, create parents before children and resolve each collectionId to the literal pbc_… id first. Never point --delete-missing at production casually. Full guide: Collections & API Rules.

10. Set env vars and tail logs

When: the deploy works but needs secrets, or it doesn’t and you need output. Prereqs: pbc login.

pbc env ls --target backend --name my-app-api        # names only — values are encrypted
pbc env set API_KEY=secret --target backend --name my-app-api
pbc env import .env.production --target backend --name my-app-api
# backends only — frontends bake vars in at build time:
# VITE_POCKETBASE_URL=… npm run build

pbc logs backend --name my-app-api -f                 # follow container stdout/stderr
pbc logs backend --name my-app-api --lines 200
pbc admin requests --filter 'level >= 8'              # instance request log, errors only

--target is pocketbase or backend — frontends take no --target. After editing vars in the portal, redeploy with --force-env. Full guides: Environment Variables, Managing Your Instance.

11. Preview on staging before prod

When: test a change on a real URL before production touches it. Prereqs: pbc login; a directory already deployed once (so pbc.json exists).

One directory holds several environments — staging and production are separate cloud resources in the same project:

pbc frontend deploy --env staging --name web-staging  # creates + links staging
pbc environments                                       # what this directory targets
pbc frontend deploy --env staging                      # iterate on the preview URL
PBC_ENV=staging pbc frontend deploy                    # same, for a whole shell
pbc frontend deploy                                    # production (defaultEnvironment)

--env works the same on info, logs, env, and rm, so pbc logs backend --env staging -f tails staging while prod keeps serving. Backends and PocketBase instances record their own dotenv file per environment; frontends have no env store, so bake preview vars into a per-env build:

// web/pbc.json
{
  "defaultEnvironment": "production",
  "environments": {
    "production": { "id": "…", "name": "web" },
    "staging": {
      "id": "…",
      "name": "web-staging",
      "build": { "command": "npm run build:staging" }
    }
  }
}

Ship the same commit to staging first, click through the preview URL, then deploy it to prod — that promotion is the release. In CI, pin one workflow per branch:

git checkout develop && pbc ci init --env staging --branch develop --out .github/workflows/deploy-staging.yml
git checkout main && pbc ci init --env production --branch main

Full guide: Installing the CLI.