CLI Reference

Complete reference for all PocketBase CLI commands and flags

PocketBase provides a powerful command-line interface for managing your backend. This page documents all available commands and their flags.

Global Flags

These flags are available for all commands and should be specified before the command name.

--dir · string · default: "./pb_data"

The PocketBase data directory where your database, migrations, and settings are stored.

./pocketbase --dir=/custom/path serve

--encryptionEnv · string

The environment variable name whose value (32 characters) will be used as the encryption key for app settings.

export PB_ENCRYPTION_KEY="your-32-character-secret-key"
./pocketbase --encryptionEnv=PB_ENCRYPTION_KEY serve

--dev · boolean · default: "false"

Enable development mode, which prints logs and SQL statements to the console for debugging.

./pocketbase --dev serve

--queryTimeout · integer · default: "30"

The default timeout for SELECT queries in seconds.

./pocketbase --queryTimeout=60 serve

---

serve

Starts the PocketBase web server with optional automatic HTTPS via Let’s Encrypt.

# Start on default port (127.0.0.1:8090)
./pocketbase serve

# Start with custom HTTP address
./pocketbase serve --http=0.0.0.0:8080

# Start with automatic HTTPS for domain(s)
./pocketbase serve --https=0.0.0.0:443 yourdomain.com

# Multiple domains with auto HTTPS
./pocketbase serve yourdomain.com api.yourdomain.com

Usage

./pocketbase serve [domain(s)] [flags]

Flags

--http · string · default: "127.0.0.1:8090"

TCP address to listen for HTTP requests.

• Default (no domains): 127.0.0.1:8090
• Default (with domains): 0.0.0.0:80

./pocketbase serve --http=0.0.0.0:8080

--https · string

TCP address to listen for HTTPS requests with automatic TLS certificate management via Let’s Encrypt.

• Default (no domains): empty (no TLS)
• Default (with domains): 0.0.0.0:443

When enabled, HTTP traffic is automatically redirected to HTTPS.

./pocketbase serve --https=0.0.0.0:443 yourdomain.com

--origins · string[] · default: "[\"*\"]"

CORS allowed domain origins list. Use this to restrict which domains can access your PocketBase API.

# Single origin
./pocketbase serve --origins="https://example.com"

# Multiple origins
./pocketbase serve --origins="https://example.com,https://app.example.com"

Domain Parameters

When you provide domain names as arguments, PocketBase automatically:

• Obtains and manages Let’s Encrypt TLS certificates
• Sets default HTTP address to 0.0.0.0:80
• Sets default HTTPS address to 0.0.0.0:443
• Redirects HTTP traffic to HTTPS

# Single domain
./pocketbase serve yourdomain.com

# Multiple domains
./pocketbase serve yourdomain.com api.yourdomain.com www.yourdomain.com

For automatic HTTPS to work, your domain(s) must point to your server’s public IP address and ports 80 and 443 must be accessible.

---

superuser

Manage superuser accounts for administrative access to your PocketBase instance.

superuser create

Creates a new superuser account.

./pocketbase superuser create [e-mail] MySecureP@ssw0rd

Success

./pocketbase superuser create [e-mail] SecurePassword123
# Successfully created new superuser "[e-mail]"!

superuser update

Changes the password of an existing superuser.

./pocketbase superuser update [e-mail] NewSecureP@ssw0rd

The superuser must already exist. Use superuser create for new accounts or superuser upsert to create or update.

superuser upsert

Creates a new superuser or updates the password if the email already exists.

./pocketbase superuser upsert [e-mail] MyP@ssw0rd123

This is the recommended command when you want to ensure a superuser exists with a specific password, regardless of whether the account already exists.

superuser delete

Deletes an existing superuser account.

./pocketbase superuser delete [e-mail]

Success

./pocketbase superuser delete [e-mail]
# Successfully deleted superuser "[e-mail]"!

superuser otp

Creates a new one-time password (OTP) for the specified superuser account.

./pocketbase superuser otp [e-mail]

Output example:

Successfully created OTP for superuser "[e-mail]":
├─ Id:    abc123def456
├─ Pass:  123456
└─ Valid: 180s

OTP authentication must be enabled for the _superusers collection for this command to work. The OTP length and validity duration are configured in the collection settings.

---

migrate

Executes database migration scripts. This command is available when the migratecmd plugin is registered.

Usage

./pocketbase migrate [command] [flags]

Commands

up

Runs all available migrations that haven’t been applied yet.

./pocketbase migrate up

down [number]

Reverts the last [number] applied migrations.

# Revert last migration
./pocketbase migrate down 1

# Revert last 3 migrations
./pocketbase migrate down 3

create [name]

Creates a new blank migration template file with the specified name.

./pocketbase migrate create add_users_table
# Creates: migrations/1234567890_add_users_table.go

collections

Creates a new migration file with a snapshot of the current collections configuration.

./pocketbase migrate collections
# Creates: migrations/1234567890_collections_snapshot.go

This is useful for version controlling your schema changes.

history-sync

Ensures that the _migrations history table doesn’t have references to deleted migration files.

./pocketbase migrate history-sync

Examples

Create Migration

./pocketbase migrate create add_verified_field
# Do you really want to create migration "migrations/1234567890_add_verified_field.go"?
# Successfully created file "migrations/1234567890_add_verified_field.go"

Migration files are created in the migrations/ directory by default (Go templates) or pb_migrations/ (JavaScript templates). The directory can be customized via plugin configuration.

---

update

Automatically updates the current PocketBase executable with the latest available version from GitHub releases. This command is available when the ghupdate plugin is registered.

./pocketbase update

Flags

--backup · boolean · default: "true"

Creates a backup of the pb_data directory at the end of the update process.

# Update without creating a backup
./pocketbase update --backup=false

# Update with backup (default)
./pocketbase update --backup=true

Process

When you run the update command, PocketBase will:

1. Fetch the latest release information from GitHub
2. Compare versions and skip if already up to date
3. Download the appropriate release for your platform
4. Extract the new executable
5. Replace the current executable
6. Create a backup (if --backup=true)
7. Display release notes

Example Output

./pocketbase update

# Fetching release information...
# Downloading pocketbase_0.23.0_linux_amd64.zip...
# Extracting pocketbase_0.23.0_linux_amd64.zip...
# Replacing the executable...
# Creating pb_data backup...
# ---
# Update completed successfully! You can start the executable as usual.
#
# Here is a list with some of the v0.23.0 changes:
# - Added new feature X
# - Fixed bug Y
# - Improved performance Z

The update command may not work as expected in Docker containers or NixOS environments. PocketBase will warn you if it detects these environments and ask for confirmation before proceeding.

---

version

Displays the current PocketBase version.

./pocketbase version
# pocketbase version 0.23.0

./pocketbase --version
# pocketbase version 0.23.0

---

help

Displays help information for PocketBase commands.

# General help
./pocketbase --help

# Help for specific command
./pocketbase serve --help
./pocketbase superuser --help
./pocketbase migrate --help

---

Example Workflows

Development Setup

# Start in development mode with custom data directory
./pocketbase --dev --dir=./dev_data serve

Production Deployment

# Production setup with HTTPS and CORS
./pocketbase serve \
  --https=0.0.0.0:443 \
  --origins="https://app.example.com,https://www.example.com" \
  example.com

Initial Setup

# 1. Create superuser
./pocketbase superuser create [e-mail] SecurePassword123

# 2. Start server
./pocketbase serve

Migration Workflow

# 1. Make schema changes in Admin UI
# (Create/modify collections)

# 2. Create migration snapshot
./pocketbase migrate collections

# 3. Apply migrations (on another environment)
./pocketbase migrate up

Backup Before Update

# Update with automatic backup
./pocketbase update

# Backups are stored in pb_data/backups/@update_v0.23.0.zip