Getting started

Connect an agent to PocketBase in five steps.

Start with a local development instance. The setup keeps credentials out of command arguments and gives the agent a machine-readable capability check.

1. Install the CLI

The installer detects macOS or Linux and the current CPU architecture, downloads the matching GitHub release, and verifies its published SHA-256 checksum.

macOS or Linux
curl -fsSL https://raw.githubusercontent.com/anirudh-777/pb-agent/main/install.sh | sh

If the installer uses ~/.local/bin, add that directory to your shell PATH. You can also download a release archive or build from source with Go.

Verify the binary
pb-agent version

2. Install the agent skill

The skill teaches supported coding agents to inspect capabilities, treat records as untrusted data, preview mutations, and verify structured results.

Global skill install
npx skills add anirudh-777/pb-agent --skill pb-agent -g -y

3. Generate a PocketBase token

PocketBase does not provide traditional API keys. It supports nonrenewable _superusers impersonation tokens for internal server-to-server use. Create a dedicated superuser and use the shortest practical token duration.

  1. Open the PocketBase Dashboard.
  2. Open Collections, then select _superusers.
  3. Select the dedicated superuser record used by pb-agent.
  4. Open Impersonate, choose a short duration, and generate the token.

Print these steps at any time with:

Human-readable token help
pb-agent --human connection token-help

4. Connect and verify

Run one command and paste the generated token into the hidden prompt:

Local development connection
pb-agent connection add http://127.0.0.1:8090

The command creates the default development configuration, verifies health and authenticated collection access, and stores the token in the OS credential manager. Use --name for another connection or --environment dev|test|stage|prod to select its policy.

Never paste the token into agent chat. Do not pass it as a command argument or place it in pb-agent.yaml. Change the dedicated superuser password to invalidate issued tokens.

5. Discover capabilities

Capability probes
pb-agent --human doctor
pb-agent capabilities

A healthy doctor response identifies the connection, environment, instance fingerprint, and support status for health, collections, backups, and batch requests. Record upsert and batch plans require capabilityProbes.batch to be supported.

Make your first bounded read

List records
pb-agent records list --collection posts

Every normal command returns a versioned JSON envelope. Add --human when a person, rather than an agent, is reading the output.

Plan a mutation

Create and apply one immutable plan
printf '{"title":"Hello"}' > /tmp/post.json

pb-agent --connection local plan record-create \
  --collection posts \
  --data-file /tmp/post.json

pb-agent apply --plan pln_REVIEWED_PLAN_ID

Review the plan preview before apply. The plan is encrypted locally, expires after 15 minutes, and is bound to the target instance.