A bounded PocketBase toolbox for agents.

Global behavior

pb-agent [--config PATH] [--connection NAME] [--human] COMMAND

• --connection selects a named PocketBase connection.
• --config selects a specific pb-agent.yaml.
• --human renders output for a person instead of the JSON contract.

Machine-readable output

Every normal command emits a versioned JSON envelope with schemaVersion, ok, command data, warnings, and a structured error when execution fails. Agents should check ok and operation-specific verification fields before reporting success.

pb-agent capabilities
pb-agent --connection local doctor

Connection and diagnostics

• connection add URL: Securely prompt for a token, verify it, store it in the OS credential manager, and create or update the configuration.
• connection token-help: Print human and machine-readable token generation guidance.
• doctor: Check health and probe collections, backups, and whether PocketBase batch requests are enabled.
• capabilities: Return implemented reads, mutations, exact command templates, server requirements, deferred work, and the approval model.

Bounded reads

Read commands are designed for inspection rather than unlimited extraction. Paginate deliberately and retrieve only the data needed for the task.

• Collections: List collection schemas or inspect one collection.
• Records: List or retrieve records from a named collection.
• Auth-rule tests: Test list rules as a guest, configured user, or supplied user.
• Files: Download a PocketBase file without overwriting an existing local file.
• Logs: Inspect PocketBase request and application logs.
• Backups: List available PocketBase backups.

pb-agent --connection local records list --collection posts

Plan/apply mutations

Mutations are split into two commands. First create a plan and review its preview. Then apply that exact plan ID. Do not regenerate a plan merely to avoid a denial or stale-state conflict.

• Records: Create, update, upsert, delete, and batch.
• Collections: Create, update, and delete schemas.
• Backups: Create, restore, and delete backups.

pb-agent --connection local plan record-update \
  --collection posts \
  --id RECORD_ID \
  --data-file update.json

pb-agent apply --plan PLAN_ID

Access grants

Staging and production mutations need a short-lived grant that matches the target connection and scope. A grant supplements the mutation plan; it does not replace review or precondition checks.

Exit and error behavior

Errors are classified for agents instead of returned as ambiguous text. Policy denial, authentication failure, invalid arguments, compatibility uncertainty, expired plans, and stale-state conflicts should stop the workflow and be reported accurately.

Deferred capabilities

The current release does not expose PocketBase settings, mail, realtime, raw HTTP, SQL, process management, or MCP. The absence of raw HTTP and SQL is a safety boundary, not a missing convenience flag.