Command Reference

Command Overview

pb-cli provides six primary commands for managing the complete development lifecycle:

Default

Build frontend + start dev server

--install

Install dependencies + build + run

--build-only

Build frontend + generate specs

--run-only

Start server without building

--production

Full production build to dist/

--test-only

Run tests with coverage reports

Default Mode (Development)

pb-cli

What It Does

Validates system requirements (Go, Node.js, npm)
Builds frontend assets (npm run build)
Copies build output to pb_public/
Prepares server environment
Starts development server (go run ./cmd/server --dev serve)

Use Cases

Standard Development Workflow

Use this as your primary development command. It ensures frontend changes are built before the server starts.

cd my-pb-ext-project
pb-cli

Server runs at http://127.0.0.1:8090 by default.

Admin panel: /_/
pb-ext dashboard: /_/_

First Time Setup

When cloning a repository for the first time, use --install instead:

git clone <repo>
cd <repo>
pb-cli --install

Output

▲ pb-cli v1.0.0 (linux/amd64)
[>] development

[>] Build Assets
[·] Frontend build (npm)
    # npm output...
[✓] Frontend built (2.3s)

[·] Preparing environment
[✓] Environment ready

[·] Starting dev server
Server started → http://127.0.0.1:8090

In development mode, OpenAPI specs are generated at runtime via AST parsing—no disk files needed.

—install

pb-cli --install

What It Does

Installs Go dependencies (go mod tidy, go mod download)
Installs npm dependencies (npm ci or npm install)
Builds frontend assets
Starts development server

Use Cases

Fresh Clone

First command to run after cloning a repository:

git clone https://github.com/yourusername/my-pb-ext-app
cd my-pb-ext-app
pb-cli --install

After Dependency Updates

When package.json or go.mod changes:

git pull
pb-cli --install

Clean Environment

Reset dependencies after corruption or conflicts:

rm -rf node_modules go.mod.sum
pb-cli --install

Dependency Installation Logic

Go Dependencies:

go mod tidy
go mod download

npm Dependencies (if package.json exists):

# If package-lock.json exists:
npm ci

# Otherwise:
npm install

—build-only

pb-cli --build-only

What It Does

Validates system requirements
Builds frontend assets
Generates OpenAPI specs (--generate-specs-dir)
Validates OpenAPI specs (--validate-specs-dir)
Exits without starting server

Use Cases

CI/CD Pipeline

Build and validate assets in continuous integration:

# .github/workflows/build.yml
- name: Build Assets
  run: pb-cli --build-only

- name: Upload Artifacts
  uses: actions/upload-artifact@v3
  with:
    name: frontend-assets
    path: pb_public/

Frontend Development

Rebuild frontend after changes without restarting the server:Terminal 1:

pb-cli --run-only

Terminal 2 (when frontend changes):

pb-cli --build-only

Refresh browser to see changes.

Pre-commit Hook

Validate builds before committing:

# .git/hooks/pre-commit
#!/bin/sh
pb-cli --build-only || exit 1

OpenAPI Spec Generation

This command generates versioned OpenAPI JSON files:

go run ./cmd/server --generate-specs-dir ./core/server/api/specs
go run ./cmd/server --validate-specs-dir ./core/server/api/specs

Output:

core/server/api/specs/
├── v1.json
├── v2.json
└── ...

—run-only

pb-cli --run-only

What It Does

Validates system requirements
Validates server setup (checks cmd/server/main.go)
Prepares server environment (creates pb_public/ if missing)
Starts development server without building frontend

Use Cases

Backend-Only Development

When working exclusively on Go code:

pb-cli --run-only

No frontend build overhead—server starts immediately.

Rapid Restart Cycles

During debugging when frontend hasn’t changed:

# First run (build + serve):
pb-cli

# Subsequent runs (serve only):
pb-cli --run-only

Separate Build Process

Use with external frontend dev server:Terminal 1 (frontend dev server):

cd frontend
npm run dev  # Runs on :5173

Terminal 2 (backend server):

pb-cli --run-only  # Runs on :8090

Ensure pb_public/ contains valid frontend assets before using --run-only. If empty, your app may not load correctly.

—production

pb-cli --production

What It Does

Cleans and creates dist/ directory
Validates system requirements
Installs dependencies (if --install also specified)
Builds frontend for production
Generates and validates OpenAPI specs
Compiles optimized server binary
Copies all assets to dist/
Runs test suite with coverage
Creates production archive (.tar.gz)

Use Cases

Deployment Build

Create production-ready artifacts for deployment:

pb-cli --production

Deploy the dist/ directory to your server.

Release Pipeline

Automated release builds in CI/CD:

# .github/workflows/release.yml
- name: Production Build
  run: pb-cli --production

- name: Upload Release Assets
  uses: actions/upload-artifact@v3
  with:
    name: production-build
    path: dist/

Custom Output Directory

Specify a different output directory:

pb-cli --production --dist release

Output: release/ instead of dist/

Production Build Output

dist/
├── pb-cli                  # Optimized binary (-ldflags="-s -w")
├── pb_public/              # Frontend assets
│   ├── index.html
│   ├── assets/
│   └── ...
├── specs/                  # Pre-generated OpenAPI specs
│   ├── v1.json
│   └── v2.json
├── test-reports/           # Test coverage and results
│   ├── test-summary.txt
│   ├── test-report.json
│   ├── coverage.html
│   └── coverage-summary.txt
├── build-info.txt          # Build metadata
├── package-metadata.json   # Package info
└── pb-ext-production.tar.gz  # Complete archive

Binary Optimization

The production binary is compiled with:

go build -ldflags="-s -w" -o dist/pb-cli ./cmd/server

Flags:

-s: Strip symbol table (reduces debugging info)
-w: Strip DWARF debugging information

Result: 30-50% smaller binary size

For deployment automation, see the pb-deployer project.

—test-only

pb-cli --test-only

What It Does

Validates system requirements
Auto-discovers test packages (walks project directory)
Runs tests with coverage tracking
Generates multiple report formats:
- test-summary.txt - Human-readable summary
- test-report.json - Machine-readable JSON
- coverage.html - Interactive HTML coverage report
- coverage-summary.txt - Function-level coverage

Use Cases

Pre-commit Validation

Verify all tests pass before committing:

pb-cli --test-only

Add to pre-commit hook:

#!/bin/sh
pb-cli --test-only || exit 1

CI/CD Testing

Automated testing in continuous integration:

# .github/workflows/test.yml
- name: Run Tests
  run: pb-cli --test-only

- name: Upload Coverage
  uses: actions/upload-artifact@v3
  with:
    name: coverage-reports
    path: dist/test-reports/

Coverage Analysis

Generate detailed coverage reports:

pb-cli --test-only
open dist/test-reports/coverage.html

Test Discovery

pb-cli automatically discovers test packages by:

Walking the project directory
Finding all *_test.go files
Extracting unique package paths
Skipping: vendor/, node_modules/, dist/, pb_data/, pb_public/, frontend/

Output Example

▲ pb-cli v1.0.0 (linux/amd64)
[>] test

[>] Test Execution
    Packages: 12

    [✓] ./core/server (45ms)
      (8 passed)
    [✓] ./core/logging (23ms)
      (5 passed)
    [✓] ./core/monitoring (67ms)
      (12 passed)
    [✗] ./core/server/api (123ms)
      (15 passed, 2 failed)

[>] Test Summary
    [✗] Tests failed (38 passed, 2 failed, 258ms)

    [i] Reports: test-summary.txt, test-report.json, coverage.html

Report Formats

test-summary.txt:

pb-cli Test Suite Summary
==============================

Execution Time: 2024-03-04 10:23:45
Duration: 258ms
Root Directory: /home/user/project

Go Version: go version go1.21.5 linux/amd64
Test Command: go run ./cmd/scripts/main.go --test-only

Status: FAILED
Error: test suite failed
Reports Directory: /home/user/project/dist/test-reports

test-report.json:

{
  "timestamp": "2024-03-04T10:23:45Z",
  "rootDirectory": "/home/user/project",
  "reportsDirectory": "/home/user/project/dist/test-reports",
  "environment": {
    "goVersion": "go version go1.21.5 linux/amd64",
    "nodeVersion": "v20.11.0",
    "npmVersion": "10.2.4"
  },
  "testSuite": {
    "command": "go run ./cmd/scripts/main.go --test-only",
    "status": "failed",
    "error": "test suite failed",
    "duration": "258ms"
  }
}

coverage.html:
Interactive HTML report with line-by-line coverage visualization

—help

pb-cli --help

Displays usage information and available commands:

▲ pb-cli v1.0.0 - PocketBase deployment automation

USAGE:
  pb-cli [options]

OPTIONS:
  --help          Show this help
  --install       Install dependencies
  --production    Production build
  --build-only    Build assets only
  --run-only      Start server only
  --test-only     Run tests only
  --dist DIR      Output directory

EXAMPLES:
  pb-cli
  pb-cli --production
  pb-cli --test-only

Combining Flags

Install + Default

pb-cli --install

Installs dependencies, builds frontend, and starts server.

Production + Custom Output

pb-cli --production --dist release

Creates production build in release/ instead of dist/.

Troubleshooting

Command not found

Problem: pb-cli: command not foundSolution: Ensure $GOPATH/bin is in your PATH:

export PATH=$PATH:$(go env GOPATH)/bin

Or use local execution:

go run cmd/pb-cli/main.go [command]

Frontend build failed

Problem: npm run build failedSolution:

Check package.json exists in frontend/
Run npm install manually to check for errors
Verify Node.js version: node --version

Check build script exists in package.json:

{
  "scripts": {
    "build": "vite build"
  }
}

Server compilation failed

Problem: go build failedSolution:

Run go mod tidy to resolve dependencies
Verify cmd/server/main.go exists
Check Go version: go version (requires 1.19+)
Review compiler errors for missing imports

Permission denied

Problem: permission denied when writing to pb_public/ or dist/Solution:

sudo chown -R $USER:$USER .
chmod -R u+w pb_public dist

Tests failing in CI but passing locally

Problem: Tests pass locally but fail in CI pipelineSolution:

Check for environment-specific dependencies

Ensure CI uses same Go/Node versions:

- uses: actions/setup-go@v4
  with:
    go-version: '1.21'
- uses: actions/setup-node@v4
  with:
    node-version: '20'

Review test isolation (check for shared state)

Next Steps

Build Pipeline

Deep dive into build orchestration internals

pb-cli Overview

Return to pb-cli overview

Quick Start

Get started with pb-ext development

Deployment

Deploy your production build

​Command Overview

Default

--install

--build-only

--run-only

--production

--test-only

​Default Mode (Development)

​What It Does

​Use Cases

​Output

​—install

​What It Does

​Use Cases

​Dependency Installation Logic

​—build-only

​What It Does

​Use Cases

​OpenAPI Spec Generation

​—run-only

​What It Does

​Use Cases

​—production

​What It Does

​Use Cases

​Production Build Output

​Binary Optimization

​—test-only

​What It Does

​Use Cases

​Test Discovery

​Output Example

​Report Formats

​—help

​Combining Flags

​Install + Default

​Production + Custom Output

​Troubleshooting

​Next Steps

Build Pipeline

pb-cli Overview

Quick Start

Deployment

Command Overview

Default Mode (Development)

What It Does

Use Cases

Output

—install

What It Does

Use Cases

Dependency Installation Logic

—build-only

What It Does

Use Cases

OpenAPI Spec Generation

—run-only

What It Does

Use Cases

—production

What It Does

Use Cases

Production Build Output

Binary Optimization

—test-only

What It Does

Use Cases

Test Discovery

Output Example

Report Formats

—help

Combining Flags

Install + Default

Production + Custom Output

Troubleshooting

Next Steps