Scaffold

Scaffold is the premier project bootstrapping tool for the Yum ecosystem. It provides a robust, template-based generation engine that eliminates boilerplate and ensures consistency across all your projects. Whether you're building a simple CLI tool, a complex web application, or an autonomous agent plugin, Scaffold gets you from zero to code in seconds.

Installation

From Source

Scaffold is built in Rust. You can install it directly from the source code:

git clone https://github.com/yum-labs/yumlabs-tools.git
cd yumlabs-tools/scaffold
cargo install --path .

Binary Download

Pre-built binaries are available for major platforms on the Releases page.

Getting Started

Scaffold operates in two primary modes: Interactive Wizard for discovery and ease of use, and CLI Mode for automation and power users.

Quick Start (Interactive Wizard)

The easiest way to start is to simply calculate the command without arguments. This launches the TUI wizard which guides you through template selection and configuration.

scaffold

What happens next?

1. Scaffold fetches the latest templates from the configured registry.
2. You select a template from the list.
3. You answer a series of prompts defined by the template (e.g., project name, features).
4. Scaffold generates the files and runs any post-generation hooks (like npm install or git init).

Advanced Usage (CLI)

For integration into scripts or pipelines, you can bypass the wizard using specific subcommands and flags.

# List available templates
scaffold list

# Run the forge scaffolding tool specifically
scaffold forge --default --output ./my-agent-plugin

Core Features

1. Template Engine

At its heart, Scaffold uses Handlebars for powerful logic-less templating. This allows templates to be flexible and dynamic without being overly complex.

• Conditional Files: Files can be included or excluded based on user input (e.g., "Do you want TypeScript?").
• Dynamic Paths: File paths themselves can contain variables (e.g., {{project_name}}/src/main.rs).
• Variable Injection: All user inputs are available as variables within the file content.

2. Multi-Source Fetching

Scaffold isn't limited to a single source. It seamlessly handles:

• Remote Repositories: Fetches templates directly from GitHub (Default: CodingInCarhartts/yum-scaffold-templates).
• Local Directories: Use --templates-dir for developing your own templates locally or working offline.
• Caching: Remote templates are cached locally to speed up subsequent runs.

3. Post-Generation Hooks

Templates aren't just files; they are workflows. Scaffold supports executing system commands after file generation.

• Dependency Installation: automatically run npm install, cargo build, etc.
• Version Control: Auto-initialize git repositories.
• Linting/Formatting: Run a formatting pass immediately after generation.

4. Interactive Wizard

The wizard dynamically builds its UI based on the template.toml definition.

• Rich Prompts: Supports Text, Boolean (Yes/No), Select (Dropdown), and Arrays.
• Validation: Ensures required fields are present and inputs match patterns.

Specification Reference

template.toml Structure

Every template must have a template.toml manifest at its root. This defines the metadata, variables, and generation rules.

[metadata]
name = "vite-ts-bun"
description = "Vite + TypeScript + Bun starter"
version = "1.0.0"
tags = ["vite", "typescript", "bun"]

[variables.project_name]
prompt = "Project name"
type = "string"
default = "my-app"
required = true

[variables.use_tailwind]
prompt = "Use Tailwind CSS?"
type = "boolean"
default = true

[[files]]
source = "files/package.json.hbs"
destination = "{{project_name}}/package.json"

[[files]]
source = "files/tailwind.config.js.hbs"
destination = "{{project_name}}/tailwind.config.js"
condition = "use_tailwind"

[[hooks]]
command = "bun"
args = ["install"]
working_dir = "{{project_name}}"
description = "Installing dependencies"

Metadata

Variables

Variables are defined under [variables.<name>].

Files

Defined as a list of [[files]].

Configuration

Scaffold can be configured globally via a config.toml file.

File Locations (in priority order):

1. ./scaffold.toml
2. $XDG_CONFIG_HOME/scaffold/config.toml (Linux/macOS)
3. ~/.config/scaffold/config.toml (Linux/macOS)
4. %APPDATA%\scaffold\config.toml (Windows)

Options

[defaults]
# Default base directory for new projects
project_directory = "~/Projects"
# Preferred package manager (bun, npm, yarn, pnpm, cargo)
package_manager = "bun"

[repositories]
# Primary registry URL
primary = "https://github.com/CodingInCarhartts/yum-scaffold-templates"
# Additional custom registries (future support)
custom = []

!NOTE If no configuration file is found, Scaffold uses internal defaults: bun as the package manager and the official defined primary repository.

Security

Scaffold executes code! Specifically:

1. Template Fetching: It downloads files from remote GitHub repositories. Ensure you trust the configured repositories.primary URL.
2. Hooks: Templates can define arbitrary shell commands in their [[hooks]] section.

   !IMPORTANT Always review the template.toml of a third-party template before running it. Scaffold will print a description of the hook before running it, but it does execute automatically.

CLI Reference

scaffold (Default)

Starts the interactive wizard.

Simulated Output:

🚀 Scaffold-CLI v0.1.0

📋 Step 1/3: Select Template
   ─────────────────────────
   ▶ 1. vite-ts-bun - Vite + TypeScript + Bun starter
     2. rust-cli    - Rust CLI tool with Clap and Tokio
     3. python-api  - FastAPI + UV starter

   Enter selection (1-3): 1

⚙️  Step 2/3: Configure Variables
   ────────────────────────────
   Project name [my-app]: demo-project
   Use Tailwind CSS? (yes/no) [yes]: yes
   Project description: A demo project

📁 Step 3/3: Target Directory
   ───────────────────────────
   Directory [./demo-project]: 

📦 Generating project...
   ✅ Created 7 files at ./demo-project

🔧 Running post-generation hooks...
   ⏳ Installing dependencies
   ✅ Installing dependencies
   ⏳ Initializing git repository
   ✅ Initializing git repository

🎉 Project created successfully at: ./demo-project

   Next steps:
   cd ./demo-project
   bun dev

scaffold list

Lists all available templates from the active fetcher.

Example:

scaffold list

Output:

📋 Available templates:

   vite-ts-bun - Vite + TypeScript + Bun starter
      Tags: vite, typescript, bun
   rust-cli - Rust CLI tool with Clap and Tokio
      Tags: rust, cli

   Use: scaffold (to start wizard)

scaffold clear-cache

Forces the removal of all locally cached GitHub templates. Useful if you want to ensure you pull the absolute latest version on the next run.

scaffold forge

Specialized scaffolder for the Autonomous Coding agent integration.

Flags:

• -d, --default: Use the default built-in app spec.
• -s, --spec <FILE>: Path to a custom app specifiction JSON/TOML.
• -i, --interactive: Launch the TUI to interactively build the spec.
• -o, --output <DIR>: Specify output directory.
• --dry-run: Show what would happen without writing files.

Example:

scaffold forge --default --output ./plugins/my-new-plugin