create-leafmesh — Project Scaffolding CLI

create-leafmesh scaffolds a complete, runnable LeafMesh project from any of the 20 ready-made teams — wiring, agent implementations, tests, Docker assets, and seed data included.

Install

pip install create-leafmesh
# or, isolated install:
pipx install create-leafmesh

This installs two commands:

Command	Purpose
`create-leafmesh`	Scaffold a new project from a template
`leafmesh-deploy`	Deploy a scaffolded project to AWS / Azure / GCP — see [Cloud Deploy](../deployment/cloud-deploy)

Pick a Template

Three ways to choose:

1. Interactive picker (recommended)

create-leafmesh my-project

With no --template flag you get an arrow-key picker in two stages — first the business category (Finance & back-office, Sales & marketing, Manufacturing, …), then the template within it, with agent counts and descriptions inline.

2. Browse from the terminal

create-leafmesh --list                        # every template, one line each
create-leafmesh --describe sales-orchestration   # full detail for one

3. Direct (CI / scripted)

create-leafmesh my-project --template customer-support

All Options

create-leafmesh [project_name] [options]

  project_name          Project directory name (prompted if omitted)
  -t, --template SLUG   Template slug (skips the picker)
  -o, --output-dir DIR  Parent directory (default: current)
  --no-git              Skip `git init` in the new project
  --list                List available templates and exit
  --describe SLUG       Show one template's details and exit
  --search QUERY        Find templates by name or description (fuzzy)
  --start DIR           Start a project you already created
  --stop DIR            Stop a running project
  --load DIR            Load the team into the store in .env (no Docker)
  --version             Print version

Create the project (2.4.509+)

Before you start, create the agency in Studio and copy its licence key and environment token. Both are shown only once.

create-leafmesh my-agency

Pick a team, then enter the licence key, the environment token, then the keys that team needs (usually a model key; more for teams that connect to other systems). It doesn't ask for a Redis address. Requires leafmesh 2.4.509 or newer.

It also writes a random LEAFMESH_VAULT_KEY and LEAFMESH_WEBHOOK_SECRET into .env. They are never printed and never replaced once set. From 2.4.507 the mesh never makes either one: with no vault key it does not start, and with no webhook secret signed webhooks answer 503. A project made earlier adds the webhook secret line by hand; the mesh says so when it starts.

What Gets Generated

my-agency/
├── agency/                # The team's Python code (auto-discovered)
├── main.py                # Starts the agency from its store
├── Dockerfile             # Production image (used by leafmesh-deploy)
├── docker-compose.yml     # Local stack incl. Redis
├── requirements.txt
├── .env                   # Licence key, environment token, store settings,
│                          # agency name, vault key, webhook secret,
│                          # CREATE_LEAFMESH_TEAM
├── .claude/skills/        # The Claude skill for this project
└── README.md              # Team-specific walkthrough

There is no configuration file in the project: no configs/config.yaml and no validate_config.py. The agency's configuration lives in its store (Redis or Postgres) and you change it in Studio. CREATE_LEAFMESH_TEAM in .env records which team the project came from.

Start It

In a terminal, create-leafmesh starts the agency straight after creating it. If you skipped a required key, it asks for it again ("Needed to start it:"). The only yes/no question is "Allowed to download it now?", before the first Docker download. It starts Redis, loads the team into the store, starts the agency and waits until it answers on /health. Then it shows:

In Studio, enter this mesh URL (Environment URLs): http://127.0.0.1:PORT

and the API docs at http://127.0.0.1:PORT/docs. Without Docker, or when not run in a terminal, it just prints create-leafmesh --start my-agency for you to run later.

The team is loaded only if the store is empty, so starting again never overwrites changes made in Studio. The blank template has no team to load: --start just starts it, and you build the team in Studio.

The agency runs without your organisation's API key, but calls to its API need it in the X-API-Key header. Create one in Studio under API Keys → Generate Key.

To start or stop a project you already created:

create-leafmesh --start my-agency      # or `create-leafmesh --start .` inside the project
create-leafmesh --stop my-agency

Without Docker

With your own Redis or Postgres set in .env:

cd my-agency
pip install -r requirements.txt
create-leafmesh --load .
python main.py

--load loads the team into the store your .env names, only if that store is empty. Then python main.py starts the agency.

Change It

After the first start, change everything in Studio. Each save is a new version and applies live, with no restart.

From a terminal:

Command	What it does
`leafmesh config export`	Write the current configuration out
`leafmesh config import`	Save a file as the next version (`--if-empty` loads it only into an empty store)
`leafmesh config check`	Check the configuration without starting
`leafmesh config versions`	List the kept versions
`leafmesh config rollback`	Go back to an earlier version

Use leafmesh config check where older guides said python validate_config.py.

Next Steps

Templates Overview — what each template's agents do and the value they bring
Cloud Deploy — push to AWS, Azure, or GCP with one command
Quick Start — build a mesh from scratch instead
Agent Development — customise the generated agents

LeafMesh, part of the LeafCraft platform