Quickstart

Install Projgen and run your first template in under two minutes.

This guide walks you through installing the CLI, running the official sample-template, and understanding how variables and steps work in practice.

---

Install the CLI

Install Projgen globally so the projgen command is available everywhere:

npm install -g @projgen/cli

You can also run any template directly without a global install using npx:

npx @projgen/cli create ./my-template.json

Projgen requires Node.js >= 18. Run node -v to check your version.

---

Run your first template

The official Projgen/templates repository contains ready-to-use templates. The simplest one is sample-template — it prompts for a name and echoes a greeting. That’s it. It’s intentionally minimal so you can see the full lifecycle without noise.

1. Run the sample template

   Point projgen create at the raw template URL:

   projgen create https://raw.githubusercontent.com/Projgen/templates/refs/heads/main/templates/sample.json
   

   Aliases c and cr work identically:

   projgen c https://raw.githubusercontent.com/Projgen/templates/refs/heads/main/templates/sample.json
   
2. Allow remote template execution

   Because the template comes from an external URL, Projgen asks you to confirm before doing anything:

   ? The template source [...] is a remote URL.
   Do you want to proceed with downloading the template? (y/N)
   

   Type y and press Enter to continue.

   Only run templates from sources you trust. A template can execute shell commands and write files on your machine.

3. Answer the prompt

   Projgen validates the template, then prompts you for every declared variable before any steps run:

   ? What's your name? › _
   

   Type your name and press Enter.

4. Watch the step execute

   After all variables are collected, Projgen runs the steps in order. The sample template has a single run step:

   Hello Alice
   

---

What just happened

Here is the complete source of the sample template so you can see exactly what ran:

{
  "id": "sample-template",
  "name": "Sample Template",
  "description": "This is a sample template for demonstration and testing purposes.",
  "version": "3.0.0",
  "engineVersion": "3.0",
  "author": "Projgen",
  "variables": [
    {
      "name": "name",
      "type": "string",
      "required": true,
      "message": "What's your name?"
    }
  ],
  "steps": [
    {
      "type": "run",
      "command": "echo",
      "args": ["Hello {{name}}"]
    }
  ]
}

Two things to notice:

• variables declares one string prompt. Because required: true, Projgen will always ask for it — -y cannot skip it (see below).
• steps declares one run step. The args array contains "Hello {{name}}" — Projgen replaces {{name}} with whatever you typed before the command runs.

{{ variableName }} interpolation works anywhere a string appears inside a step — in command, args, path, content, cwd, url, or value. The substitution happens at execution time, after all prompts are answered.

---

Add a template to your local registry

Instead of passing a file path or URL every time, register the template under an alias:

projgen add https://raw.githubusercontent.com/Projgen/templates/refs/heads/main/templates/sample.json my-template

Now run it by alias from anywhere:

projgen c my-template

If you omit the alias, Projgen uses template.id as the alias (sample-template in this case). The registry will reject a projgen add call if either the alias or the id is already registered — templates are stored by id filename, so duplicates are not allowed.

Run projgen list (alias: projgen ls) at any time to see all registered templates, the registry version, and any linked registries.

---

Skipping prompts with -y

Add -y to skip any variable prompt that is either optional (required: false) or has a default value. Projgen will use the default or leave the value empty without asking.

projgen create my-template -y

Variables that are required: true with no default are always prompted, even with -y. There is no way to suppress a required variable without a default — Projgen needs a value to proceed.

Variable config	Behaviour with -y
required: true, no default	Always prompted — cannot be skipped
required: true, has default	Skipped — default value used
required: false, no default	Skipped — value is empty / null
required: false, has default	Skipped — default value used

In the sample template, name is required: true with no default, so -y has no effect — you will still be asked for it.

---

What’s next

Introduction

Understand how the CLI, Template Engine, and registry fit together.

CLI commands

Full reference for create, add, list, and remove.

Template spec

All variable types, step types, and condition operators.

Official templates

Browse production-ready templates from the Projgen team.