pbctl

Infrastructure-as-Code for PocketBase.

pbctl is a Rust CLI for managing PocketBase schemas with PBSL (PocketBase Schema Language) and collection access rules.

Instead of creating and editing collections manually in the PocketBase Admin UI, you define your schema and rules in files, keep them in git, and use pbctl to validate, plan, export, and apply changes.

Your files are the source of truth. PocketBase is the runtime state.

Installation

From source (via Cargo)

cargo install pbctl

Pre-built binaries

Download the latest binary for your platform from the releases page.

# Linux / macOS
chmod +x pbctl-*
./pbctl-* --help

# Windows
pbctl.exe --help

What this gives you

• Declarative schema definitions (PBSL)
• Declarative access rules (.pb rules files)
• -- line comments in schema files
• Human-readable, git-friendly files
• Validation and formatting for both schema and rules
• A diff-based plan step before changes are applied
• Safer schema changes with system collection protection
• Field-level diffing (type changes, modifier changes, drops, renames)
• Advanced field options (max file size, MIME types, cascade delete, max select)
• Graceful handling of missing relation targets
• System/in-built collection relation support (users, pb_users_auth)
• Semantic validation (modifier/type compatibility)
• A live PocketBase client layer
• Auth, view, and index support
• An interactive REPL for fast iteration

Quick start

pbctl init                          # create config + schema.pbsl + rules.pb
pbctl login                         # authenticate against PocketBase
pbctl validate -f schema.pbsl       # check schema syntax
pbctl rules validate -f rules.pb    # check rules syntax
pbctl plan -f schema.pbsl           # preview schema changes
pbctl rules plan -f rules.pb        # preview rule changes
pbctl apply -f schema.pbsl          # apply schema changes
pbctl rules apply -f rules.pb       # apply rule changes

Workflow

PocketBase
   │
   │ export
   ▼
schema.pbsl  +  rules.pb
   │
   │ validate / fmt
   ▼
plan / rules plan
   │
   │ apply / rules apply
   ▼
PocketBase

The intended loop:

1. Export the live schema and rules.
2. Commit the files to git.
3. Review changes in plan or rules plan.
4. Apply them deliberately.
5. Repeat until PocketBase and your files match.

Core commands

Schema management

pbctl init          # initialize config, schema.pbsl, and rules.pb
pbctl login         # authenticate against PocketBase
pbctl whoami        # show active connection
pbctl collections   # list live collections

pbctl validate -f schema.pbsl   # validate PBSL syntax
pbctl fmt -f schema.pbsl        # format PBSL file in-place

pbctl export        # export live schema + rules to schema.pbsl and rules.pb
pbctl plan -f schema.pbsl       # diff local schema vs live PocketBase
pbctl apply -f schema.pbsl      # apply schema changes

pbctl apply -f schema.pbsl --dry-run   # preview without applying
pbctl apply -f schema.pbsl --prune     # allow collection deletion

Rules management

pbctl rules export              # export live rules to rules.pb
pbctl rules validate -f rules.pb   # validate rules file syntax
pbctl rules fmt -f rules.pb        # format rules file in-place
pbctl rules plan -f rules.pb       # diff local rules vs live PocketBase
pbctl rules apply -f rules.pb      # apply rule changes
pbctl rules apply -f rules.pb --dry-run  # preview rule changes

Interactive shell

pbctl shell      # launch interactive REPL
pbctl repl       # alias for shell

Rules file format

Access rules are stored in a rules.pb file using a simple key-value format:

# users rules
collection: users
list: "id = @request.auth.id"
view: "id = @request.auth.id"
create: ""
update: "id = @request.auth.id"
delete: "id = @request.auth.id"

# posts rules
collection: posts
list: "@request.auth.id != ''"
view: "@request.auth.id != ''"
create: "@request.auth.id != ''"
update: "user = @request.auth.id"
delete: "user = @request.auth.id"

Each section starts with collection: <name> followed by the five rule types:

• list — who can list/view items
• view — who can view a single item
• create — who can create items
• update — who can update items
• delete — who can delete items

Set a rule to null or "" to allow unrestricted access (or no restriction). Set it to a PocketBase filter expression to restrict access.

Safety model

pbctl is built around conservative operations:

• System collections are protected from accidental modification.
• plan and rules plan are read-only — they never mutate PocketBase.
• apply and rules apply only execute changes based on the plan.
• Unknown collections are treated as unmanaged unless --prune is passed.
• --dry-run previews changes before any mutation.
• Re-running apply converges toward no changes.

Documentation

• PBSL reference — full schema language specification
• Architecture
• CLI reference
• Configuration
• Internals
• Roadmap
• Contributing

Examples live in docs/Examples.

Repository layout

src/
  apply/        apply engine for schema changes
  cli.rs        CLI definitions
  config.rs     configuration loading/saving
  diff/         diff engine and migration plan
  error.rs      error types
  main.rs       entry point and command handlers
  pb/           PocketBase client and models
  pbsl/         lexer, parser, AST, formatter, validator
  repl/         interactive shell
  rules/        rules format, parser, and CollectionRules model
  util/         helpers

tests/
  parser_tests.rs

work/
  schema.pbsl
  rules.pb

Status

The project includes complete building blocks for schema-as-code:

• lexer, parser, AST, formatter, validator for PBSL
• diff planner with field-level change detection
• apply executor with Dry-run support
• PocketBase REST client
• Collection rules management (export, plan, apply, validate, fmt)
• Auth, view, and index support
• Relation name resolution in export
• REPL shell