Quick Start for Developers

In about thirty minutes you will have the leed CLI installed, your site’s repository cloned and rebuilding on http://localhost:8080 as you type, and one template change live on your preview site. This is the condensed happy path; each step links to the page that covers it exhaustively. One thing is worth checking before you start, because it is the only part you cannot fix yourself: your account needs developer access, and an administrator grants it.

If you want the architecture before the commands — what the repository is, and how it relates to the CMS — read How Leed Fits Together first. Otherwise, start here.

Before you start

Three things:

• Git. The installer checks for it and stops if it is missing.
• Bun 1.1.0 or later. The CLI runs on Bun. If it is absent or out of date the installer offers to install or update it for you; declining ends the install.
• Developer access. This is an override an Administrator grants by ticking the Developer checkbox next to your name on Settings → Team Members. Without it the installer gets as far as downloading your project configuration and stops with “Your account needs developer access.” — an authorization failure, not a bug in your setup.

The installer supports macOS, Linux and WSL. On WSL it opens your browser through wslview; if it cannot open a browser on any platform it prints the URL for you to paste instead.

An Administrator grants developer access with the Developer checkbox described in Billing and Developer Access — the same page covers what that override does and does not unlock.

1. Get your install command

In the CMS, open the profile menu — your avatar at the bottom of the left rail — and choose Developer Setup. The dialog shows your prerequisites and your install command:

curl -fsSL https://app.leed.ai/install | bash

2. Run the installer

Paste the command into a terminal. It runs unattended apart from three prompts, and here is what it does with your answers:

1. Checks Git and Bun, offering to install or update Bun if needed.
2. Signs you in, using a device-authorization flow. It prints a code formatted like ABCD-1234 and opens app.leed.ai/auth/device in your browser. Check that the code on screen matches the one in your terminal, approve it, and the terminal continues. You have five minutes before the code expires.
3. Asks where to put your project, defaulting to ~/leed. If that folder already holds a leed.config.json it asks before overwriting it.
4. Downloads leed.config.json — this is the step that needs developer access.
5. Installs the CLI globally with Bun, after writing the private registry into ~/.bunfig.toml.
6. Runs leed site init, which clones your site repository into ~/leed/<your-domain>/raw-content and checks out the staging branch.

When it finishes, confirm the install:

leed -V

Every installer step in detail, the credentials file it writes, self-update and shell completion are in Installing the Leed CLI; how the device login works, where the token lives and how it refreshes is CLI Authentication.

3. Build and serve

cd ~/leed/<your-domain>
leed site build --serve

The first build renders your whole site — templates, your published CMS content, Tailwind CSS and the search index — and then starts a local server at http://localhost:8080. Leave it running. Edits to templates, partials and Tailwind files rebuild the affected pages automatically; refresh the browser to see them. Ctrl+C stops the server and cleans up.

Templates are Handlebars, so this is the moment How Templates Work starts paying for itself, with every helper you can call from one listed in the Helper Index (A–Z). Styling is Tailwind driven from site.config.css — see How Styling Works.

These are the flags worth knowing on day one:

That last column is not trivia. Read the --debug trap below before you settle into a habit.

The full watch loop, the remaining flags and a worked session are in Local Development; every flag has a row in leed site build.

4. Make a change you can see

With the server running, open your site folder and change something obvious. A layout under src/_layouts/ or a partial under src/_includes/ is a good first target: change a heading, add a class, save the file, and watch the terminal rebuild and the browser show it.

You are looking at a normal Eleventy project with Leed’s conventions on top. Layouts and partials are .hbs, styling is Tailwind under tailwind/, static files sit in src/static/, and your CMS content is injected at build time rather than living in the repo as source you edit. What is actually in the folder you just cloned is described in Your Site Repository — and some of it you may not edit at all, which Editable and Read-Only Files enumerates before validation does it for you.

5. Validate, commit and push

Shipping is four commands, always in this order, because each one gates the next:

leed site validate            # every changed file is allowed
leed site build               # a plain build — no --serve, no --debug
leed site commit -m "Refreshed the footer layout"
leed site push

There is no git add: the CLI stages your changes itself. Commits are only accepted on the staging branch, which is where leed site init left you, and the repository’s git hooks reject a bare git commit or git push so the checks cannot be skipped by accident.

Your push is traced end to end in What Happens After You Push, and the promotion step is Promoting Preview to Live. The four-step contract itself, the staging-only rule and the automatic rebase are in Validate, Commit and Push; if a command exits non-zero, CLI Troubleshooting and Exit Codes has every code and message.

Here is the whole loop, including the two edges that catch people out — the plain build being a gate rather than a step, and the push exiting to preview rather than live:

flowchart LR
  Edit["Edit files under src/"] --> Serve["leed site build --serve"]
  Serve --> Review["Review at localhost:8080"]
  Review -->|Not there yet| Edit
  Review -->|Happy with it| Validate["leed site validate"]
  Validate --> Build["leed site build<br/>plain, no flags"]
  Build -->|Gate — commit refuses without a recorded build| Commit["leed site commit -m ..."]
  Commit --> Push["leed site push"]
  Push --> PreviewSite["Preview site"]
  PreviewSite -.->|Promote on the Deploy screen| LiveSite["Live site"]

The --debug trap

This one deserves its own heading because it costs people an afternoon.

leed site commit refuses to run unless there has been a successful build since your last edit. It checks a recorded build timestamp — and --debug builds are not recorded, because their output is unminified and therefore not what would ship. So a developer who has settled into leed site build -d will be told, forever, to run a build they have just run:

You must run the following command before changes can committed: leed site build

Let Claude Code drive it

leed site init installs more than the repository. It also writes git hooks, a VS Code workspace with tasks for every command on this page, and three Claude Code skills into the project: site-builder, which knows Leed’s helpers, partials and conventions for building layouts and styles; site-preview, which handles builds and the dev server; and site-publish, which runs the validate → build → commit → push sequence including its failure and rebase paths.