CLI

Commands

pbkit generate

Generate types and SDK from your pbkit.config.ts.

bunx pbkit generate

Options

Flag	Short	Description
--config <path>	-c	Path to a config file (defaults to auto-detection)
--watch	-w	Watch mode — regenerates every 10 seconds
--help	-h	Show help message

pbkit schema

Manage PocketBase collection definitions directly against the admin API (/api/collections). Schema-only — record CRUD is intentionally out of scope.

pbkit schema list                       # list all collections (name + type)
pbkit schema get <collection>           # dump one collection as JSON
pbkit schema pull [--out pb-schema.json]# download the full snapshot the generator reads
pbkit schema apply <file.json>          # import definitions (non-destructive)
pbkit schema add-field <collection> <json>
pbkit schema add-index <collection> "<sql>"
pbkit schema set-rule <collection> [--list <rule>] [--view <rule>] [--create <rule>] [--update <rule>] [--delete <rule>]
pbkit schema create-view <name> --query "<sql>"

Subcommands

Command	Description
list	List every collection with its name and type
get <collection>	Print one collection (fields, indexes, rules, viewQuery) as JSON
pull [--out <file>]	Write the full schema snapshot (default pb-schema.json) — the same shape pbkit generate consumes
apply <file>	Import collection definitions via PUT /api/collections/import
add-field <collection> <json>	Append a field, preserving the existing fields array
add-index <collection> "<sql>"	Append an index, merging with existing indexes
set-rule <collection> --list/--view/--create/--update/--delete <rule>	Update API rules (only the provided ones)
create-view <name> --query "<sql>"	Create a view collection

Options

Flag	Description
--config <path>	Config file used for fallback URL/token (auth env vars take precedence)
--out <file>	Output path for pull (default pb-schema.json)
--delete-missing	For apply, remove collections absent from the file (default off)
--query <sql>	View query for create-view
--list/--view/--create/--update/--delete <rule>	Rules for set-rule

apply is non-destructive by default (deleteMissing: false). Partial operations (add-field, add-index, set-rule) fetch the current collection and patch it, so they never clobber unrelated fields, indexes, or rules. For set-rule, a rule value of "null" makes the rule superuser-only and "" makes it public.

Authentication

Schema commands authenticate as a superuser (_superusers/auth-with-password). Credentials are read from the environment (preferred), falling back to the pbkit.config.ts API input — never inline.

Variable	Purpose
POCKETBASE_URL	PocketBase base URL
POCKETBASE_ADMIN_EMAIL	Superuser email (used with the password)
POCKETBASE_ADMIN_PASSWORD	Superuser password
POCKETBASE_ADMIN_TOKEN	Pre-issued admin token (alternative to email/password)

pbkit logs

Read PocketBase’s request and app logs from the admin API (/api/logs), like tail for your server. Uses the same superuser authentication as pbkit schema.

pbkit logs                          # last 50 logs, oldest first
pbkit logs -n 200 --level warn      # last 200 warnings and errors
pbkit logs --since 1h --errors      # failing requests and error logs from the last hour
pbkit logs --slow 1000 -v           # requests that took 1s or more, with details
pbkit logs --filter 'data.status>=500'
pbkit logs -f                       # keep printing new logs as they arrive
pbkit logs --json | jq .            # raw records, one JSON object per line
pbkit logs get <id>                 # one log as pretty JSON
pbkit logs stats [--since 24h]      # hourly log counts
pbkit logs top [--since 24h]        # per-endpoint calls, errors and latency

Each log prints on one line: time, level, then for request logs the method, status, URL and how long the request took (12ms, 1.4s); other logs show their message. If the log has an error, it is appended at the end. In a terminal, slow requests stand out: latency is yellow above 500ms and red above 2s. Colors are turned off when output is piped or NO_COLOR is set.

Options

Flag	Short	Description
--limit <n>	-n	How many recent logs to show (default 50)
--since <dur>		Only logs from the last 30m, 1h, 24h, 7d, …
--level <name>		Minimum level: debug, info, warn or error
--slow <ms>		Only requests that took at least this many milliseconds
--errors		Only failing requests (status 400 and up) and error-level logs
--filter <expr>		Any PocketBase filter (e.g. data.status>=400)
--include-self		Also show the CLI’s own /api/logs requests (hidden by default)
--verbose	-v	Print a second, indented line under request logs with auth, IP, referer, userAgent and details (empty fields are left out)
--json		Print raw records, one JSON object per line
--follow	-f	Poll every 2 seconds and print new logs as they arrive
--config <path>	-c	Config file used for fallback URL/token (auth env vars take precedence)

All the narrowing flags (--since, --level, --slow, --errors, --filter) combine with AND. stats accepts --since, --filter and --json.

PocketBase writes logs to its database in batches, so with --follow new entries can show up a few seconds after the request happened. That is normal.

pbkit logs top

Groups request logs by method and route and shows, per endpoint: number of calls, number of errors (status 400 and up), and the p50, p95 and max request time. Routes are normalized so they group well: the query string is dropped, record ids become :id, and file URLs become /api/files/<collection>/:id/:file.

Flag	Short	Description
--since <dur>		Time window (default 1h)
--sort <key>		latency (p95, the default), errors or calls
--limit <n>	-n	Rows to show (default 20)
--max <n>		Stop after fetching this many logs (default 20000)
--slow, --errors, --level, --filter, --include-self		Same as for pbkit logs
--json		Print the summary as JSON

Percentiles use the nearest-rank method, so each value is a real request time from the window.

Finding slow or failing endpoints

Start with the overview, then look at the individual requests:

pbkit logs top --since 24h          # which endpoints are slow or failing?
pbkit logs --slow 1000 -v           # the requests that took 1s or more, with who made them

Use pbkit logs top --sort errors to rank by failures instead of latency.

For a step-by-step walkthrough, see Find slow endpoints.

Two things to keep in mind:

• The timing is for the whole HTTP request as PocketBase saw it, not for individual SQL queries. A slow endpoint tells you where to look, not which query is to blame.
• top downloads the logs in the window to your machine and does the math there. It asks only for the fields it needs and pages gently, but on a busy server it stops at --max logs (default 20000) and warns you that the result is partial. Narrow --since or raise --max if that happens.

Config auto-detection

pbkit searches for a config file in the current working directory in this order:

1. pbkit.config.ts
2. pbkit.config.js
3. pbkit.config.mjs

Watch mode

bunx pbkit generate --watch

In watch mode, pbkit polls the API (or re-reads the file) every 10 seconds and regenerates if the schema has changed. Press Ctrl+C to stop.

Custom config path

bunx pbkit generate --config ./configs/pbkit.config.ts

Exit codes

Code	Meaning
0	Success
1	Error (config not found, API error, invalid config)

Example output

$ bunx pbkit generate
  src/generated/types.gen.ts
  src/generated/client.gen.ts
  src/generated/sdk.gen.ts
Generated 3 file(s) in 120ms