pocketbase
Skill for operating PocketBase backend via REST API and Go package mode. Provides collection CRUD, record CRUD, superuser/user authentication, backup & restore, migration file generation (JS and Go), Go hooks, custom routes, and design guidance for API rules, relations, and security patterns. Use for requests related to PocketBase, pb_migrations, collection management, record operations, Go framework embedding, and backend design.
How do I install this agent skill?
npx skills add https://github.com/ikumasudo/pocketbase-skill --skill pocketbaseIs this agent skill safe to install?
- Gen Agent Trust Hubfail
The skill facilitates the management of a PocketBase backend through administrative scripts and comprehensive documentation. It includes a bootstrap process to download the official binary from GitHub and uses standard environment files for secret management. Security considerations include the generation of migration scripts from templates and the inherent surface for indirect prompt injection when processing database records.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
11/27 files flagged
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
PocketBase Skill
Operate PocketBase backend projects (standalone binary or Go package mode) with bundled Python scripts and references.
Skill Resources
Use resources in this skill directory first:
scripts/- executable helpers for auth, collections, records, backups, migration template generationreferences/- detailed backend docs to load on demandassets/- migration templates
Prefer --help output and this guide first. If behavior is unclear, read only the relevant script file.
0. Fast Start
Mode Detection
- If
go.modcontainsgithub.com/pocketbase/pocketbase-> Go package mode - Otherwise -> standalone mode
Bootstrap (when PocketBase is not running)
- Resolve latest version dynamically:
VERSION=$(curl -s https://api.github.com/repos/pocketbase/pocketbase/releases/latest | python3 -c "import sys,json; print(json.load(sys.stdin)['tag_name'].lstrip('v'))")
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
OS=$(uname -s | tr A-Z a-z)
curl -sL "https://github.com/pocketbase/pocketbase/releases/download/v${VERSION}/pocketbase_${VERSION}_${OS}_${ARCH}.zip" -o pb.zip
unzip -o pb.zip pocketbase && rm pb.zip
- Create superuser:
./pocketbase superuser create admin@example.com <password>
- Configure
.env(and keep.envin.gitignore):
PB_URL=http://127.0.0.1:8090
PB_SUPERUSER_EMAIL=admin@example.com
PB_SUPERUSER_PASSWORD=your-password
- Start service:
nohup ./pocketbase serve --http=127.0.0.1:8090 > pb.log 2>&1 &
- Health check:
python scripts/pb_health.py
As of 2026-02-27, latest stable release is v0.36.5.
1. Design & Safety Checklist
Your model priors may include pre-v0.23 patterns. Validate these before any schema or hook changes.
v0.23+ Critical Rules
- Use
_superusers(not_admins) - Use collection
fields(notschema) - Use flat field properties (no
optionswrapper) - Use typed field constructors in migrations (
TextField,SelectField,RelationField, ...) - Use
{param}path syntax in routes (not:param) - JSVM hooks must call
e.next(); Go hooks mustreturn e.Next() @collection.*filters should use?=when multiple rows are possible
API Rule Defaults
null-> superuser only""-> public (including unauthenticated)
Default to null and open only what is required.
Go Mode Checks
- Use API/Admin UI for collection changes; let PocketBase auto-generate migrations
- Commit generated files in
pb_migrations/ - Configure
migratecmd.MustRegister(..., migratecmd.Config{Automigrate: true})for dev - Ensure blank import exists when manual migrations are used:
_ "yourmodule/migrations" - For rule assignment in manual Go migrations, use
types.Pointer("...")
2. Core Operations
2.1 Authentication
Superuser auth:
python scripts/pb_auth.py
User auth:
python scripts/pb_auth.py --collection users --identity user@example.com --password secret
2.2 Collections
List / get:
python scripts/pb_collections.py list
python scripts/pb_collections.py get posts
Create / update / delete:
python scripts/pb_collections.py create --file schema.json
python scripts/pb_collections.py update posts --file updates.json
python scripts/pb_collections.py delete posts
Batch import (recommended for multi-collection setup):
python scripts/pb_collections.py import --file collections.json
Important:
- Do not create a new
userscollection; update the existing one - Use
--filewhen payload includes API rules to avoid shell quote issues - For
fieldsupdates, send full field set (not partial merge)
2.3 Records
python scripts/pb_records.py list posts --filter 'status="published"' --sort "-created" --expand "author"
python scripts/pb_records.py get posts <recordId>
python scripts/pb_records.py create posts --file record.json
python scripts/pb_records.py update posts <recordId> '{"status":"published"}'
python scripts/pb_records.py delete posts <recordId>
2.4 Backups
python scripts/pb_backups.py list
python scripts/pb_backups.py create
python scripts/pb_backups.py restore <backupKey>
python scripts/pb_backups.py delete <backupKey>
Restore replaces all data; always create a backup before restore.
2.5 Migrations
Primary workflow (both modes):
- Start PocketBase
- Change collections via API/Admin UI
- Commit auto-generated migration in
pb_migrations/
Manual migration template generation (only for seed/data transform/raw SQL):
python scripts/pb_create_migration.py "backfill_user_slugs"
python scripts/pb_create_migration.py "seed_categories" --dir ./pb_migrations
3. Verification
After schema or rule changes, run:
python scripts/pb_collections.py get <collection>- CRUD smoke test (create/list/get/update/delete)
- Rule test with non-superuser token
Rule-denied behavior reference:
listRuledenied ->200with emptyitemsviewRuledenied ->404createRuledenied ->400updateRuledenied ->404deleteRuledenied ->404nullrule for regular users ->403
E2E tests are required when non-null API rules or custom hooks/routes exist. Use references/e2e-testing.md and scripts/pb_e2e_helpers.py.
Minimum E2E coverage:
- Unauthenticated access denied
- Authenticated allowed path succeeds
- Cross-user access blocked
- Owner spoofing in create payload blocked
cascadeDeletebehavior verified- Custom route auth enforcement verified
- Hook side effects verified
4. Reference Map
Read only what is needed:
- Common pitfalls:
references/gotchas.md - API rules:
references/api-rules-guide.md - Collections API:
references/collections-api.md - Records API:
references/records-api.md - Auth API:
references/auth-api.md - Migrations (JS):
references/migrations.md - Field types:
references/field-types.md - Relation patterns:
references/relation-patterns.md - File handling:
references/file-handling.md - JSVM hooks:
references/jsvm-hooks.md - Go setup:
references/go-framework.md - Go migrations:
references/go-migrations.md - Go hooks/routes:
references/go-hooks-routes.md - E2E testing:
references/e2e-testing.md
Frontend integration work belongs to pb-react-spa skill.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/ikumasudo/pocketbase-skill/pocketbase">View pocketbase on skillZs</a>