quickstart.mdx

title	Quickstart
description	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.

Point `projgen create` at the raw template URL:

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

Aliases `c` and `cr` work identically:

```bash
projgen c https://raw.githubusercontent.com/Projgen/templates/refs/heads/main/templates/sample.json
```

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.

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

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.

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

Understand how the CLI, Template Engine, and registry fit together. Full reference for `create`, `add`, `list`, and `remove`. All variable types, step types, and condition operators. Browse production-ready templates from the Projgen team.