Skip to main content

​
Overview

pb-cli is the official build toolchain for pb-ext projects. It automates frontend builds, OpenAPI spec generation, server compilation, testing, and production deployments through a unified CLI interface.
pb-cli handles the full development lifecycle from dependency installation to production-ready binaries.

​
Why pb-cli?

Manually coordinating frontend builds, Go compilation, OpenAPI spec generation, and test execution is error-prone and time-consuming. pb-cli provides:
  • Unified workflow: Single command for build + serve
  • Smart detection: Auto-detects frontend type (npm, static, or none)
  • OpenAPI automation: Generates and validates specs for production
  • Production optimization: Stripped binaries with -ldflags="-s -w"
  • Test automation: Full coverage reports with multiple formats
  • CI/CD ready: Designed for automation pipelines

​
Installation

Install pb-cli as a global binary available anywhere on your system: 
go install github.com/magooney-loon/pb-ext/cmd/pb-cli@latest
Verify installation: 
pb-cli --help
Ensure $GOPATH/bin or $HOME/go/bin is in your PATH:
export PATH=$PATH:$(go env GOPATH)/bin

​
Local Execution

Run directly from the pb-ext repository without installing: 
go run cmd/pb-cli/main.go [command]

​
Programmatic Usage

Import as a package in your Go applications: 
import "github.com/magooney-loon/pb-ext/pkg/scripts"

func main() {
    scripts.RunCLI()
}

​
Quick Start

​
Development Mode

Build frontend and start development server: 
pb-cli
This runs:
  1. System validation (checks Go/Node/npm)
  2. Frontend build (npm run build)
  3. Assets deployment (copy to pb_public/)
  4. Server startup (go run ./cmd/server --dev serve)

​
Install Dependencies

Install all project dependencies (Go modules + npm packages): 
pb-cli --install

​
Build Assets Only

Compile frontend and generate OpenAPI specs without starting the server: 
pb-cli --build-only

​
Start Server Only

Skip frontend build and start the development server immediately: 
pb-cli --run-only

​
Production Build

Create optimized production binary and assets: 
pb-cli --production
Output directory: dist/ (customizable with --dist)

​
Run Tests

Execute test suite with coverage reports: 
pb-cli --test-only

​
System Requirements

Go

Version 1.19 or higher

Node.js

Version 16 or higher

npm

Version 8 or higher
pb-cli automatically validates system requirements before executing operations.

​
Command Reference

For detailed command documentation, see:

Commands

Complete command reference with examples and use cases

Build Pipeline

Deep dive into the build orchestration process

​
Key Features

​
Smart Frontend Detection

pb-cli automatically detects your frontend type:
  • npm-based: Runs npm install and npm run build, copies output to pb_public/
  • Static files: Directly copies files to pb_public/
  • No frontend: Skips frontend build steps

​
OpenAPI Spec Generation

For production builds, pb-cli:
  1. Runs go run ./cmd/server --generate-specs-dir ./core/server/api/specs
  2. Validates generated specs with --validate-specs-dir
  3. Copies specs to dist/specs/ for disk-based loading
In development mode, specs are generated at runtime via AST parsing—no disk files needed.

​
Test Automation

When running tests (--test-only or during production builds):
  • Auto-discovers test packages by walking the project directory
  • Runs tests with structured output
  • 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 breakdown

​
Production Optimization

Production builds (--production) create optimized binaries: 
go build -ldflags="-s -w" -o dist/pb-cli ./cmd/server
Flags:
  • -s: Strip symbol table
  • -w: Strip DWARF debugging info
Result: Significantly smaller binary size

​
Output Directories

​
Development Mode

project/
├── pb_public/          # Frontend assets (served by PocketBase)
├── pb_data/            # PocketBase database (created on first run)
└── core/server/api/specs/  # OpenAPI specs (runtime generation)

​
Production Mode

dist/
├── pb-cli              # Optimized server binary
├── pb_public/          # Frontend assets
├── specs/              # Pre-generated OpenAPI specs
├── test-reports/       # Test coverage and results
├── package-metadata.json
├── build-info.txt
└── pb-ext-production.tar.gz  # Complete archive

​
Next Steps

Command Reference

Explore all available commands and flags

Build Pipeline

Understand the build orchestration internals

Quick Start Guide

Get started with pb-ext development

Deployment

Deploy your production build