BuzzerBoy DevOps Toolkit

A DevOps automation toolkit available in two flavors: bbi (full AI + deploy) and bbi-lite (deploy & scaffold only, safe for CI/CD pipeline runners).

Table of Contents

1. Two Binaries — Why?
2. Quick Reference: Commands by Binary
3. Installation
4. Using bbi-lite
5. Using bbi (Full)
6. Future: Public npm for bbi-lite

Two Binaries — Why?

| Binary | Purpose | AI Required | Typical User | |---|---|---|---| | bbi | Full toolkit — AI generation + deploy | Yes | Developers, local machine | | bbi-lite | Deploy & scaffold only | No | CI/CD pipeline runners, LNineDevops templates |

The problem bbi-lite solves: Pipeline runners using LNine deploy or LNineDevops templates cannot install the full bbi binary because of its size and AI agent dependencies. bbi-lite contains only the commands needed to deploy, scaffold, and manage infrastructure — no AI, no heavy dependencies, installs cleanly in any pipeline.

Both binaries are built from the same repository and installed together with a single npm link.

Quick Reference: Commands by Binary

| Command | bbi | bbi-lite | Notes | |---|:---:|:---:|---| | deploy app | ✓ | ✓ | Deploy app via buzzerboy.cfg.json | | deploy file | ✓ | ✓ | Deploy a single file to FTP (GenericFTP only) | | deploy architecture | ✓ | ✓ | Deploy infra via buzzerboy.cfg.json | | deploy legacy | ✓ | ✓ | Legacy Lightsail deploy via CLI flags | | init | ✓ | ✓ | Create buzzerboy.cfg.json | | mimic | ✓ | ✓ | Mirror deployment env locally | | cleanup | ✓ | ✓ | Remove old Lightsail container images | | migrate | ✓ | ✓ | Django database migrations | | newProject create | ✓ | ✓ | Scaffold new project from template | | setup linux / setup macos | ✓ | ✓ | Install dev toolchain | | connect ec2ssh / connect ec2exec | ✓ | ✓ | SSH/exec into EC2 instances | | appMaker | ✓ | — | AI app generation | | architectureMaker | ✓ | — | AI architecture documentation | | proposalMaker | ✓ | — | AI consulting proposals | | codeReview | ✓ | — | AI code review | | codeAssist | ✓ | — | AI documentation & feature implementation | | synthesizer | ✓ | — | AI knowledge base synthesis | | uikit | ✓ | — | AI HTML → Django conversion | | bbiMaker | ✓ | — | AI CLI command generation | | azDo | ✓ | — | Azure DevOps integration | | newProject architecture | ✓ | — | Architecture scaffolding (pending AI impl) | | newProject scaffoldSaas | ✓ | — | Clone & customize base SaaS template with AI landing page |

Installation

Prerequisites

• Node.js v14 or higher (v20 recommended)
• Python v3.8 or higher (for certain utilities)
• AWS CLI configured with appropriate credentials
• Docker (for deployment features)
• Git

Full Install — bbi + bbi-lite

Installs both binaries globally. Use this on developer machines.

# Clone the repository
git clone https://github.com/buzzerboyinc/devops-bbi
cd devops-bbi

# Install dependencies
npm install

# Build all binaries + install prompt/config files
npm run compile

# Link globally (installs both bbi and bbi-lite)
npm run setup

# Verify
bbi --version
bbi-lite --version

Lite-Only Install — bbi-lite for pipeline runners

Use this when you only need deploy commands and want to avoid AI dependencies.

cd devops-bbi

npm install

# Build only bbi-lite binary and link globally
npm run install-lite

# Verify
bbi-lite --version

npm Scripts Reference

| Script | What it does | |---|---| | npm run compile | Build all binaries + run configure.js (AI prompts, config files) | | npm run compile-lite | Build only bbi-lite binary | | npm run setup | sudo npm link — registers all bin entries globally | | npm run install-lite | compile-lite + sudo npm link in one step |

Using bbi-lite

Global Options

bbi-lite has a reduced set of global options (no AI flags):

| Option | Description | Default | |---|---|---| | --verbose | Enable verbose logging | false | | --config-file <file> | Path to configuration file | buzzerboy.cfg.json in current dir | | -V, --version | Display version number | — | | -h, --help | Display help | — |

bbi-lite [global-options] <command> [command-options]

bbi-lite init

Create a buzzerboy.cfg.json configuration file in the current directory. Required before running deploy app or deploy architecture.

bbi-lite init [options]

Options:

| Option | Description | |---|---| | -p, --product <product> | Product name | | -a, --app <app> | App name | | -o, --organization <org> | Organization name | | -t, --tiers <tiers> | Tiers: dev-stg-prd, dev-prd, dev-demo-prd, or custom comma-separated | | -r, --region <region> | AWS region (ca-central-1, us-east-1) | | --architecture <arch> | Architecture type (AWSLightSail, AWSTransactionalApps, GenericFTP) |

Any omitted option will be prompted interactively.

# Fully prompted
bbi-lite init

# Fully specified
bbi-lite init -p ecommerce -a shop -o buzzerboy -t dev-stg-prd -r ca-central-1 --architecture AWSLightSail

bbi-lite deploy

Deploy applications or infrastructure. Reads configuration from buzzerboy.cfg.json by default.

bbi-lite deploy app

Deploy an application. Routes to the correct deployment handler based on architecture in your config (AWSLightSail, AWSTransactionalApps, or GenericFTP).

bbi-lite deploy app [options]

| Option | Description | |---|---| | -t, --tier <tier> | Deployment tier (defaults to dev) | | -p, --product <product> | Override product name from config | | -a, --app <app> | Override app name from config | | -o, --organization <org> | Override organization from config | | -r, --region <region> | Override region from config | | -h, --allowedHostsCsv <hosts> | Comma-separated allowed hosts (AWSLightSail only) |

# Deploy to dev (reads all values from buzzerboy.cfg.json)
bbi-lite deploy app

# Deploy to staging
bbi-lite deploy app -t stg

# Deploy to production with allowed hosts
bbi-lite deploy app -t prd -h "shop.example.com,www.shop.example.com"

bbi-lite deploy file

Upload a single local file to an FTP server (--architecture GenericFTP only). Unlike deploy app, this does not walk a directory tree and does not support --clean — it uploads exactly one file to <tier>/<remoteDir>/<filename>.

bbi-lite deploy file --architecture GenericFTP --tier <tier> --source <path> [options]

| Option | Description | |---|---| | -t, --tier <tier> | Deployment tier (remote root folder) | | --architecture <architecture> | Must be GenericFTP | | -s, --source <path> | Local path to the file to upload | | -f, --filename <name> | Target filename on the remote server (defaults to source basename) | | --remoteDir <path> | Optional. Subpath under the tier folder to upload into (e.g. www/download) | | --protocol <protocol> | Optional. ftp (default), ftps (implicit TLS), ftpes (explicit TLS) | | --no-overwrite | Optional. Skip upload if the remote file already exists (default: overwrite) |

# Upload an installer to a specific subfolder under the tier
bbi-lite deploy file --architecture GenericFTP --tier theferryapp.com \
  --source ./downloads/Ferry-Windows.msi --filename Ferry-Windows.msi \
  --remoteDir www/download --protocol ftpes

# Skip upload if the remote file already exists
bbi-lite deploy file --architecture GenericFTP --tier geteddytor.com \
  --source ./downloads/EddyTor-win.msi --remoteDir www/download --no-overwrite

bbi-lite deploy architecture

Deploy infrastructure using buzzerboy.cfg.json.

bbi-lite deploy architecture [-t <tier>]

# Examples
bbi-lite deploy architecture
bbi-lite deploy architecture -t prd

bbi-lite deploy legacy

Legacy Lightsail deployment — all values supplied via CLI flags (no config file needed).

bbi-lite deploy legacy -p <product> -a <app> -t <tier> [options]

| Option | Description | |---|---| | -p, --product <product> | Product name (required) | | -a, --app <app> | App name (required) | | -t, --tier <tier> | Tier name (required) | | -h, --allowedHostsCsv <hosts> | Comma-separated allowed hosts | | -o, --organization <org> | Organization name | | -r, --region <region> | AWS region |

bbi-lite deploy legacy -p ecommerce -a shop -t dev

bbi-lite migrate

Run Django database migrations against the specified tier.

bbi-lite migrate -p <product> -a <app> -t <tier> [options]

| Option | Description | |---|---| | -p, --product <product> | Product name (required) | | -a, --app <app> | App name (required) | | -t, --tier <tier> | Tier name (required) | | -o, --organization <org> | Organization name | | -r, --region <region> | AWS region |

bbi-lite migrate -p ecommerce -a shop -t dev

bbi-lite cleanup

Remove old Lightsail container images, keeping the N most recent.

bbi-lite cleanup -p <product> -a <app> -t <tier> [options]

| Option | Description | |---|---| | -p, --product <product> | Product name (required) | | -a, --app <app> | App name (required) | | -t, --tier <tier> | Tier name (required) | | -n, --number <number> | Number of images to keep (default: 5) | | -o, --organization <org> | Organization name | | -r, --region <region> | AWS region |

bbi-lite cleanup -p ecommerce -a shop -t dev -n 3

bbi-lite mimic

Set up a local development environment that mirrors a deployment tier (retrieves secrets, configures env).

bbi-lite mimic -p <product> -a <app> -t <tier> [options]

| Option | Description | |---|---| | -p, --product <product> | Product name (required) | | -a, --app <app> | App name (required) | | -t, --tier <tier> | Tier to mirror (required) | | -h, --allowedHostsCsv <hosts> | Comma-separated allowed hosts | | -o, --organization <org> | Organization name | | -r, --region <region> | AWS region |

bbi-lite mimic -p ecommerce -a shop -t dev

bbi-lite newProject

Scaffold a new project from a template.

bbi-lite newProject create

bbi-lite newProject create -t <type> -n <name> [options]

| Option | Description | |---|---| | -t, --type <type> | Project type (see --help for supported types) | | -n, --name <name> | Project name (required) | | -p, --product <product> | Product name (for package projects) | | --use-ssh | Use SSH for cloning instead of HTTPS |

bbi-lite newProject create -t webapp -n my-shop
bbi-lite newProject create -t api -n my-api --use-ssh

bbi-lite setup

Install development toolchains. Runs scripts from GitHub.

# Linux (and WSL) — run as sudo
bbi-lite setup linux [--force]

# macOS
bbi-lite setup macos [--force]

--force continues past failures in individual setup steps.

bbi-lite connect

Connect to EC2 instances. Automatically authorizes your current IP for access.

bbi-lite connect ec2ssh

bbi-lite connect ec2ssh -p <product> -a <app> -t <tier> -i <instance>

bbi-lite connect ec2exec

bbi-lite connect ec2exec -p <product> -a <app> -t <tier> -i <instance> -c "<command>"

| Option | Description | |---|---| | -p, --product <product> | Product name | | -a, --app <app> | App name | | -t, --tier <tier> | Tier name | | -i, --instance <name> | EC2 instance name or ID | | -c, --command <command> | Command to execute (ec2exec only) |

Typical Pipeline Workflow

# --- Pipeline runner setup (once, when provisioning the runner) ---
cd devops-bbi
npm install
npm run install-lite

# --- Per-deployment pipeline steps ---

# 1. Initialize config (only needed if buzzerboy.cfg.json doesn't exist in the repo)
bbi-lite init -p myproduct -a myapp -o mybiz -t dev-stg-prd -r ca-central-1 --architecture AWSLightSail

# 2. Deploy app to the target tier
bbi-lite deploy app -t dev

# 3. Run database migrations (Django projects)
bbi-lite migrate -p myproduct -a myapp -t dev

# 4. Clean up old images after a successful deploy
bbi-lite cleanup -p myproduct -a myapp -t dev -n 5

Using bbi (Full)

bbi includes everything in bbi-lite plus the AI-powered commands:

| Command | Description | |---|---| | bbi appMaker | Generate app requirements and components using AI | | bbi architectureMaker | Generate architecture documentation using AI | | bbi proposalMaker | Generate consulting proposals using AI | | bbi codeReview | AI-assisted code review (Django, Node CLI) | | bbi codeAssist | AI documentation updates and feature implementation | | bbi synthesizer | Synthesize knowledge bases using AI | | bbi uikit html2django | Convert HTML UI kits to Django projects using AI | | bbi bbiMaker | Generate new CLI commands for bbi using AI | | bbi azDo | Azure DevOps integration (PR creation, ticket management) | | bbi newProject scaffoldSaas | Clone a base SaaS template (django | laravel-react), customize branding, and populate landing page with AI |

AI commands support --agent (claude, codex, copilot), --dry-run, and --outputDir global flags.

bbi newProject scaffoldSaas

Clones a base SaaS template (django or laravel-react — a full SaaS app with team, account, and settings management), applies your branding, generates architecture and pipeline files, writes buzzerboy.cfg.json, and uses AI to populate the landing page from a requirements document.

bbi newProject scaffoldSaas --type <django|laravel-react> --name <displayName> --product <product> --app <app> \
  --tiers <dev-stg-prd> --architecture <type> [options]

| Option | Required | Description | |---|---|---| | --type <type> | Yes | Template type: django | laravel-react | | -n, --name <name> | Yes | Product display name — used as folder slug | | -p, --product <product> | Yes* | Product identifier (e.g. my_saas) | | -a, --app <app> | Yes* | App name (e.g. cms) | | --tiers <tiers> | Yes* | Deployment tiers, dash-separated (e.g. dev-stg-prd, dev-prd) | | --architecture <type> | Yes** | AWSLightSail | AWSTransactionalApps | GenericFTP | | --skip-architecture | No | Skip creating the architecture/ folder | | --skip-pipelines | No | Skip creating the pipelines/ folder | | --brand-color <hex> | No | Brand color as 6-char hex without # (e.g. 2e6392) | | -r, --requirements <path> | No | Path to a requirements.md for AI landing page content | | --agent <agent> | No | AI agent: claude, codex, or copilot (default: copilot) | | --use-ssh | No | Clone via SSH instead of HTTPS | | --dry-run | No | Print the AI command without executing it |

* Required unless both --skip-architecture and --skip-pipelines are set ** Required unless --skip-architecture is set

Requirements file: If --requirements is not provided, the command looks for requirements.md in the current directory. If none is found, it prompts whether to continue with generic placeholder content.

# Full scaffold — branding, architecture, pipelines, config, AI landing page
bbi newProject scaffoldSaas \
  --type django \
  --name "TeamFlow" \
  --product teamflow \
  --app cms \
  --tiers dev-stg-prd \
  --architecture AWSTransactionalApps \
  --brand-color 2e6392 \
  --requirements tests/test-data/saas-scaffold/requirements.md

# Laravel + React (Inertia) variant
bbi newProject scaffoldSaas \
  --type laravel-react \
  --name "TeamFlow" --product teamflow --app cms \
  --tiers dev-stg-prd --architecture AWSTransactionalApps --brand-color 2e6392

# Dry run — see AI command without executing
bbi newProject scaffoldSaas \
  --type django \
  --name "TeamFlow" --product teamflow --app cms \
  --tiers dev-stg-prd --architecture AWSTransactionalApps --dry-run

# Skip infrastructure files (branding + AI landing page only)
bbi newProject scaffoldSaas \
  --type django \
  --name "My SaaS" --skip-architecture --skip-pipelines --brand-color 2e6392

What it does:

1. Clones the selected template (django → template-saas-django, laravel-react → template-saas-laravel-react) into a slugified folder (teamflow/)
2. Removes the .git folder — clean slate, no history
3. Updates 00_platform_customization.json with product_name and optionally the brand color (brand_color for django, brand_color_light/brand_color_dark for laravel-react)
4. For django: replaces PLACEHOLDER LOGO in logo.html with [TeamFlow] - Placeholder (no-op for laravel-react, which brands via logo URLs instead of an HTML placeholder)
5. Creates architecture/ with main.py, cdktf.json, requirements.txt from the selected architecture type
6. Creates pipelines/ with one YAML file per tier (e.g. teamflow-cms-dev.yml, teamflow-cms-stg.yml, teamflow-cms-prd.yml)
7. Writes buzzerboy.cfg.json with product, app, tiers, architecture, and region defaults
8. Runs AI to rewrite landing page content — pages/landing/landing.html and includes/landing/ for django, or resources/js/Pages/Marketing/*.tsx for laravel-react

See OLD-README.md for the full command reference, options, workflows, and AI configuration.

Full Install

npm run compile   # Build all binaries + configure AI prompts/config
npm run setup     # sudo npm link — installs bbi and bbi-lite globally

Future: Public npm for bbi-lite

bbi-lite is structured to be published to the public npm registry, enabling pipeline runners to install it without cloning this repository:

# Future (not yet published)
npm install -g bbi-lite

When published, runners will no longer need access to this private repository. The bbi-lite package will include only the deploy/scaffold dependencies — no AI runtime, no md-to-pdf, no Puppeteer.