This guide walks you through generating your first project without registering any account. All local features of the open-source edition are free forever (MIT license), and your data stays on your own machine.

Step 1: Install the CLI

npm install -g agilebuilder
ag --version

Requires Node.js ≥ 20 and Git on your machine — see Install.

Step 2: Create a project directly from a Git template

Any publicly accessible Git repository works as a template source — no registration step needed:

ag create --git-url https://github.com/example/template.git --target ./my-app

Common options (--branch picks a branch, --subdir uses a subdirectory as the template root, --var passes template variables — all optional):

ag create --git-url https://github.com/example/template.git \
  --target ./my-app \
  --branch main \
  --subdir templates/node \
  --var appName=my-app \
  --var useAuth=true

The CLI clones the template repository, renders variables (EJS syntax such as <%= appName %>), and writes the result into the --target directory. If the target directory exists and is not empty, you must pass --overwrite explicitly.

--var parses true, false, null, and numbers into their scalar types; everything else stays a string. For many variables, pass them in bulk with --vars vars.json.

Interactive variable prompts

When the template author has defined questions in .agilebuilder.config.yaml, add --interactive to have the CLI prompt you for each missing variable:

ag create --git-url https://github.com/example/template.git \
  --target ./my-app --interactive

Step 3: Register frequently used templates for one-command creation

Typing full Git URLs every time is tedious. Register templates in your local workspace with ag res add:

ag space use local    # use the built-in local workspace (the default; no sign-in needed)

ag res add template \
  --name web-app \
  --git-url https://github.com/example/template.git \
  --branch main \
  --tags "web,starter"

Then create projects by resource ID:

ag res list                 # list registered templates and find the ID
ag create 1 --target ./my-app --var appName=my-app

Other useful local resource commands:

ag res search web           # search by keyword
ag res get 1                # show details
ag res edit 1 --name new-name
ag res remove 1 --yes       # deletion requires explicit confirmation

Step 4 (optional): Allow template Hooks

Templates can define Hooks that run after files are written (currently only after_write shell scripts, e.g. running npm install in the generated directory). For safety, Hooks do not run by default — you must authorize them explicitly:

ag create 1 --target ./my-app --allow-hooks

If you trust your own templates, you can make this the default:

ag config set template.allowHooksDefault true

What the open-source edition can and can't do

Capability	Open source (local)
Create projects from a Git URL / local resources	✅
Template variable rendering, Hooks	✅
Local template/doc resource management	✅
MCP server for AI tools	✅
Cloud spaces, multi-device sync	❌ (requires registration — see Pro Quickstart)
Team-shared template library	❌ (see Team Quickstart)

The local workspace works fully offline: no sign-in, no network — create, res, and friends work as usual (cloning a template does require access to its Git host, of course).

Next steps

Core Concepts — resources, variables, Hooks, and spaces explained
Create a Template — turn your own project into a template
MCP Integration — let AI tools call your template library