Inspect with bounds
List collections, records, logs, and backups through paginated commands with structured output.
Open source · Agent first · PocketBase
Give your agent PocketBase access. Keep control.
pb-agent is a safe PocketBase CLI for AI coding agents. Let agents inspect collections, test rules, manage records, and prepare schema changes without handing them unrestricted database access.
Apache-2.0 · Local-first · Pre-release · PocketBase 0.39.8 baseline
$ pb-agent --connection local doctor ✓ health supported ✓ collections supported ✓ backups supported $ pb-agent plan record-update \ --collection posts --id rec_42 \ --data-file update.json plan pln_7e2f expires 15 minutes changes title, published $ pb-agent apply --plan pln_7e2f ✓ precondition verified ✓ mutation applied ✓ audit evidence written
JSON-firstStable envelopes for agents
Plan, then applyNo mutable write arguments
Read-only productionUntil a scoped grant exists
Local audit evidenceMetadata and hashes, not values
The working model
Useful enough for development. Restrained enough for real data.
Agents need more than read-only context to finish features and tests. pb-agent gives them the operations they need, then puts a durable boundary around every write.
Review one fixed plan
Mutation data is encrypted locally and bound to the target instance, environment, request hash, and expiry.
Apply with fresh checks
Updates and deletes verify current state immediately before execution, then write metadata-only audit evidence.
Safety is executable
Policy lives in the tool, not in the prompt.
A careful system prompt is useful guidance. It is not an access-control boundary. pb-agent applies the same rules no matter which coding agent runs it.
Expiring mutation plans
Plans expire after 15 minutes, are single-use, and cannot be retargeted.
Production is read-only by default
Staging and production mutations need an explicit, short-lived grant with matching scope.
Credentials stay out of agent output
Tokens enter through stdin, live in the OS keychain, and are recursively redacted from responses.
Stale writes stop
Optimistic concurrency checks abort updates and deletes when a target changed after planning.
Choose the right boundary
Not another broad database tool.
pb-agent is designed for agent-driven PocketBase work. It intentionally omits raw SQL and arbitrary HTTP so safety controls cannot be bypassed.
| Capability | pb-agent | Generic MCP server | Ad hoc SDK script |
|---|---|---|---|
| Works across coding agents | Yes, via CLI + skill | Only MCP-capable hosts | Manual integration |
| Immutable write preview | Built in | Implementation-dependent | Build it yourself |
| Production read-only default | Enforced | Implementation-dependent | Build it yourself |
| Stale-state protection | Before apply | Implementation-dependent | Build it yourself |
| Raw SQL or HTTP escape hatch | Intentionally absent | Often available | Usually available |
Install once
CLI for capability. Skill for judgment.
The binary enforces policy and talks to PocketBase. The agent skill teaches compatible coding agents how to inspect first, plan writes, request approval, and verify structured results.
Install the CLI · macOS and Linux
curl -fsSL https://raw.githubusercontent.com/anirudh-777/pb-agent/main/install.sh | sh
Install the agent skill
npx skills add anirudh-777/pb-agent --skill pb-agent -g -y
Prefer to inspect before running? Read the installer source or use the release archives directly.
Common questions
PocketBase agent access, answered.
What is pb-agent?
pb-agent is an open-source CLI and agent skill that gives AI coding agents structured access to PocketBase. It supports bounded reads and reviewable plan-then-apply mutations while enforcing environment-aware safety policy.
Why use it instead of a PocketBase MCP server?
A JSON-first CLI works across agent hosts and keeps the safety boundary independent of one protocol. An MCP adapter can still sit on top later, but it should not own policy.
Can an agent write to production?
Not by default. Production connections are read-only until a human creates a short-lived access grant with the required operation and resource scope. The agent still needs an immutable plan.
Does pb-agent store my PocketBase password?
No. It uses a nonrenewable superuser impersonation token and stores it in the operating system credential manager. The token is not written to configuration, output, plans, or audit logs.
Which PocketBase operations are supported?
Reads cover health, collections, records, auth-rule testing, file downloads, logs, and backups. Plan/apply mutations cover records, batches, collections, and backups. Run pb-agent capabilities for the current machine-readable catalog.
Is pb-agent affiliated with PocketBase?
No. pb-agent is an independent open-source project. PocketBase is a trademark of its respective owner.
Let the agent finish the PocketBase work.
Start locally, inspect the plan, and keep the boundary explicit.