Welcome to Projgen

Template-driven project scaffolding. Define a JSON template once, run it anywhere.

Projgen is a CLI tool for scaffolding new projects from declarative JSON templates. Instead of manually bootstrapping boilerplate every time, you define variables (user prompts) and steps (actions) in a single .json file — then let Projgen handle the rest: running shell commands, writing files, patching text or JSON configs, and cloning setups with a single command.

Templates are portable, versionable, and composable. You can store them locally, share them via the official templates registry, or maintain your own private registry. The core CLI is available globally via npm and requires no configuration to get started.

npm install -g @projgen/cli

---

The Projgen ecosystem

Projgen is made up of three layers that work together.

Projgen CLI

The command-line interface. Install it globally and use projgen create, add, list, and remove to run templates and manage your local registry. Currently on v3.

Template Engine

The internal engine that loads, validates, and executes template JSON. It resolves variables, evaluates when conditions, and dispatches steps through typed adapters. Currently on v3.1.

Official Templates

The Projgen/templates repository. A curated registry of ready-to-use templates — from sample starters to full TypeScript CLI setups.

The CLI and the Template Engine are versioned independently. The CLI is currently v3 and the Template Engine is v3.1. Your template’s engineVersion field declares which engine version it targets.

---

How it works

1. Install the CLI

   Install globally with npm or run directly with npx — no config file required.

   # Install globally
   npm install -g @projgen/cli
   
   # Or run without installing
   npx @projgen/cli create ./my-template.json
   
2. Write (or grab) a template

   A template is a .json file with metadata, a variables array (user prompts), and a steps array (actions to run). Here is the minimal structure:

   {
     "$schema": "https://raw.githubusercontent.com/Projgen/core/refs/heads/master/template.schema.json",
     "id": "my-template",
     "name": "My Template",
     "description": "A short description of what this template creates.",
     "version": "1.0.0",
     "engineVersion": "3.1",
     "author": "Your Name",
     "variables": [],
     "steps": []
   }
   

   Or use an official template directly from the registry.

3. Run it

   Point projgen create at the file path, url or a registry alias. Projgen validates the template, prompts for any declared variables, then executes all steps in order.

   # From a local file
   projgen create ./my-template.json
   
   # From a url
   projgen create https://raw.githubusercontent.com/Projgen/templates/refs/heads/main/templates/sample.json
   
   # From a registry alias (after projgen add)
   projgen create my-template
   
   # Skip optional prompts (only required variables without defaults are asked)
   projgen create my-template -y
   

---

What a template can do

A template declares variables that are prompted before any work starts, and steps that consume those values.

Variables

Four types of input are supported:

Type	Description	Key fields
string	Free-text input	required, default
number	Numeric input	required, default
boolean	True/false toggle	default
select	Single choice from a list	required, options
multi-select	Multible choices from list	required, options

Variables are referenced inside step fields using {{variableName}} — in paths, commands, content, and JSON values.

Steps

Steps run in declaration order after all variables are collected. Any step can be guarded with a when condition array.

run

Execute a shell command. Supports command, args[], and optional cwd.

write

Create or overwrite a file. Content can be inline or fetched from a url.

patch-text

Surgically edit a text file: replace, insert-after, insert-before, append, or prepend.

patch-json

Modify a JSON file at a jsonPath using set, append, or remove.

---

Jump in

Quickstart

Run your first template in under two minutes.

Template spec

Full reference for variables, steps, and conditions.

Official templates

Browse ready-made templates maintained by the Projgen team.

GitHub

Source code, issues, and contributions.