@c137labs/buildfast-cli

Production-grade CLI for C-137 BuildFast Scaffold — composable Next.js template for AI-First ventures with layers.

Features

• Scaffold new ventures with layer selection
• Composable layers — pick exactly what you need (core, saas, ai, billing, realtime, i18n…)
• Interactive menus — checkbox layer picker with auto-detection of installed layers
• Progress display — listr2 task lists for every operation
• CI-friendly — auto-adapts to non-TTY, supports --no-input / --json / --no-color
• Health checks — Node/npm/git/layers/TypeScript via buildfast doctor
• Self-update — buildfast update keeps the CLI current
• Shell completion — tab-complete commands and flags
• "Did you mean?" — typo suggestions for unknown commands

Installation

npm install -g @c137labs/buildfast-cli@latest

# Verify
buildfast --version

# On macOS with permission errors
npm install --prefix ~/.npm-global @c137labs/buildfast-cli@latest
export PATH="$HOME/.npm-global/bin:$PATH"

Usage

Scaffold a new venture

# Interactive (recommended)
buildfast scaffold

# Non-interactive
buildfast scaffold --name my-app --layers core,saas
buildfast scaffold --name my-app --layers core,saas,ai,realtime
buildfast scaffold --name my-app --layers core,saas --auth auth0

# CI / scripting
buildfast scaffold --name my-app --layers core,saas --no-input
buildfast scaffold --name my-app --layers core,saas --json   # JSON output
buildfast scaffold --name my-app --layers core,saas --dry-run  # preview only

What it does: prompts → clones template → strips unselected layers → updates package.json → git init → npm install → TypeScript validation.

Available auth providers: supabase (default, magic link), auth0 (OTP + enterprise SSO + M2M)

Add layers

# Interactive — opens a checkbox menu, detects installed layers automatically
buildfast add

# Direct — add specific layers
buildfast add saas
buildfast add saas billing-b2c
buildfast add redis realtime   # redis auto-added when realtime is selected

# Flags
buildfast add ai --dry-run     # preview without changing files
buildfast add ai --no-input    # non-interactive (CI)
buildfast add ai --json        # machine-readable output

Interactive mode (buildfast add with no args):

• Clones template and loads the manifest
• Scans your package.json to detect already-installed layers
• Shows a checkbox menu — installed layers appear as ✓ name (installed) and are disabled
• Only newly selected layers are applied

Available layers:

| Layer | Description | Requires | |-------|-------------|----------| | core | Next.js, Auth, DB, Observability | — | | saas | Multi-tenant workspaces, RBAC | core | | billing-b2c | Stripe subscriptions, plans | saas | | billing-b2b | Enterprise contracts, quotes | billing-b2c | | ai | LiteLLM, LangGraph, Langfuse, pgvector, RAG | core | | redis | Upstash Redis, typed cache, rate limiting | core | | realtime | Job queues, pub/sub, live updates | redis | | i18n | next-intl internationalization + Crowdin | core | | copilot | CopilotKit AI UX | ai | | magic-ui | Animated landing components | — | | ai-elements | Voice, canvas, code UI | ai |

Remove layers

buildfast remove ai
buildfast remove ai copilot

# Skip confirmation prompt
buildfast remove ai --force

# Preview without changes
buildfast remove ai --dry-run

Safety: always prompts for confirmation before removing files (bypass with --force). Creates backup branch backup/remove-modules before removal.

Health check

buildfast doctor

Runs all checks as a task list and reports pass/fail:

| Check | What it verifies | |-------|-----------------| | Node.js >= 18 | Correct runtime version | | npm | Package manager present | | git | Optional, needed for scaffold/remove | | Project structure | package.json, tsconfig.json, next.config.ts | | Layers manifest | scripts/layers.json / modules.json | | Dependencies | node_modules exists | | Environment | .env.local present | | TypeScript | Zero type errors |

Update CLI

buildfast update

Checks npm registry for a newer version and installs it globally if one is available.

Shell completion

# Add to your shell profile
eval "$(buildfast completion zsh)"    # zsh
eval "$(buildfast completion bash)"   # bash

# Fish — write to completions directory
buildfast completion fish > ~/.config/fish/completions/buildfast.fish  # fish

Commands Reference

| Command | Description | |---------|-------------| | buildfast scaffold | Create a new venture from template | | buildfast add [layers...] | Add layers (interactive if no args) | | buildfast remove <layers...> | Remove layers with confirmation | | buildfast doctor | Run all health checks | | buildfast update | Update the CLI to the latest version | | buildfast completion [shell] | Print shell completion script |

Global flags

| Flag | Description | |------|-------------| | --dry-run | Preview all actions without making changes | | --no-input | Non-interactive mode (CI/scripting) | | --json | Machine-readable JSON output | | --no-color | Disable terminal colors | | --version | Show CLI version | | --help | Show help |

Development

npm install
npm run build       # compile TypeScript → dist/
npm run dev         # run without compiling (tsx)
npm run typecheck   # type check only
npm run lint        # ESLint
npm test            # vitest
npm run test:watch  # vitest watch mode

File Structure

buildfast-cli/
├── src/
│   ├── commands/
│   │   ├── scaffold.ts    # buildfast scaffold
│   │   ├── add.ts         # buildfast add (interactive + direct)
│   │   ├── remove.ts      # buildfast remove (with confirmation)
│   │   ├── doctor.ts      # buildfast doctor (listr2 task list)
│   │   ├── update.ts      # buildfast update (self-update)
│   │   └── completion.ts  # buildfast completion (shell scripts)
│   ├── core/
│   │   ├── modules.ts     # layer manifest loading
│   │   └── git.ts         # git operations
│   ├── utils/
│   │   ├── ci.ts          # TTY/CI detection, color support
│   │   ├── errors.ts      # structured error formatting
│   │   ├── fuzzy.ts       # levenshtein / "Did you mean?"
│   │   ├── summary.ts     # post-operation summary display
│   │   ├── onboarding.ts  # first-run welcome message
│   │   ├── files.ts       # file operations
│   │   ├── npm.ts         # package management
│   │   ├── logger.ts      # colored logging (errors → stderr)
│   │   └── banner.ts      # ASCII banner (silent in CI)
│   └── index.ts           # CLI entry point
├── package.json
├── tsconfig.json
├── tsup.config.ts
└── README.md

Technical Stack

| Package | Version | Purpose | |---------|---------|---------| | Commander | 11.1 | CLI framework | | Inquirer | 9.2 | Interactive prompts | | Listr2 | 8.0 | Task list progress display | | Ora | 7.0 | Spinners | | Chalk | 5.3 | Terminal colors | | update-notifier | 7.3 | Background update checks | | execa | 8.0 | Process execution | | simple-git | 3.22 | Git operations | | fast-glob | 3.3 | File globbing | | fs-extra | 11.2 | File operations |

Requirements

• Node.js >= 18
• npm >= 9
• git (required for scaffold and remove)

License

Copyright (c) 2025 C-137 Labs. All rights reserved.

This software is proprietary and not open source. You may use the CLI to scaffold your own projects, but you may not copy, modify, redistribute, or resell this software. Generated project output belongs entirely to you.

See LICENSE for full terms.

Support

• Documentation: https://docs.c137labs.com
• Issues: https://github.com/c137labs/buildfast-cli/issues