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 base SaaS template, 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 the template-saas-base repo (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 --name <displayName> --product <product> --app <app> \
  --tiers <dev-stg-prd> --architecture <type> [options]

| Option | Required | Description | |---|---|---| | -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 \
  --name "TeamFlow" \
  --product teamflow \
  --app cms \
  --tiers dev-stg-prd \
  --architecture AWSTransactionalApps \
  --brand-color 2e6392 \
  --requirements tests/test-data/saas-scaffold/requirements.md

# Dry run — see AI command without executing
bbi newProject scaffoldSaas \
  --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 \
  --name "My SaaS" --skip-architecture --skip-pipelines --brand-color 2e6392

What it does:

1. Clones template-saas-base 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 brand_color
4. Replaces PLACEHOLDER LOGO in logo.html with [TeamFlow] - 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 in pages/landing/landing.html and includes/landing/

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.