pb-cli - pb-ext

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

Global Installation (Recommended)

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:

System validation (checks Go/Node/npm)
Frontend build (npm run build)
Assets deployment (copy to pb_public/)
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:

Runs go run ./cmd/server --generate-specs-dir ./core/server/api/specs
Validates generated specs with --validate-specs-dir
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

​Overview

​Why pb-cli?

​Installation

​Global Installation (Recommended)

​Local Execution

​Programmatic Usage

​Quick Start

​Development Mode

​Install Dependencies

​Build Assets Only

​Start Server Only

​Production Build

​Run Tests

​System Requirements

Go

Node.js

npm

​Command Reference

Commands

Build Pipeline

​Key Features

​Smart Frontend Detection

​OpenAPI Spec Generation

​Test Automation

​Production Optimization

​Output Directories

​Development Mode

​Production Mode

​Next Steps

Command Reference

Build Pipeline

Quick Start Guide

Deployment

Overview

Why pb-cli?

Installation

Global Installation (Recommended)

Local Execution

Programmatic Usage

Quick Start

Development Mode

Install Dependencies

Build Assets Only

Start Server Only

Production Build

Run Tests

System Requirements

Command Reference

Key Features

Smart Frontend Detection

OpenAPI Spec Generation

Test Automation

Production Optimization

Output Directories

Development Mode

Production Mode

Next Steps