CLI Command Reference

This is the index. It shows the whole leed command tree, the options that apply everywhere, and where each command’s own flags are written up. Every command in the tree accepts --help, at any depth — leed site commit --help prints that command’s synopsis and options — so this page exists to answer the other question: which command, and where is it documented.

The command tree

Twenty-three command leaves ship. * marks the ones hidden from --help.

leed
├── auth
│   ├── login
│   ├── logout
│   ├── status
│   ├── rotate
│   └── reset
├── login                       alias of `leed auth login`
├── site
│   ├── init
│   ├── build
│   ├── validate
│   ├── commit
│   ├── push
│   ├── generate
│   ├── import
│   ├── create-page-type
│   ├── list
│   ├── eject
│   ├── upload              *
│   └── notify-cms          *
├── schema
├── self-update
├── completion              *
│   ├── install             *
│   └── uninstall           *
└── completion-server       *

Global options

These are declared on the root program, so every command accepts them however deeply nested it is.

--json has its own page: the envelope, the fourteen error codes and the rules for consuming them are on machine-readable output.

Reading the logger filter

Channels are named leed:<area>:<level> — leed:app:error, leed:site:build:info, leed:auth:debug — and -n takes the same wildcard patterns the debug package uses. The default, *:error, matches every :error channel from every library that uses debug, which is why a quiet run still tells you when something breaks. -v is a shorthand and nothing more: it is precisely -n leed:*, every level of every Leed channel. Pass both and they combine, as leed:*,<your filter>.

Every leed:* channel writes to stderr, in both human and JSON mode. They are diagnostics, not a command’s answer, so leed site list > types.txt captures the table and none of the logging.

Eleventy’s internals are a separate matter, because Eleventy loads its own copy of debug and reads the raw DEBUG variable:

DEBUG=Eleventy* leed site build

An inherited DEBUG is merged into the CLI’s own filter rather than replacing it. And once the namespaces are registered, the CLI deletes DEBUG from the environment whenever no Eleventy channel ended up enabled — a deliberate performance workaround, because Eleventy checks that variable to decide whether to run character-set detection on every template it reads. The practical consequence is that DEBUG=* does not behave the way you would expect from other tools. Use -n for Leed channels and DEBUG=Eleventy* for Eleventy’s.

leed auth

Five subcommands managing the session the CLI holds, plus the two GitLab tokens your site checkout depends on. None of them needs a site directory except rotate and reset, which are scoped to one site.

What the session actually is, where it lives and how it stays alive is the subject of CLI authentication.

leed login

leed login

A top-level alias for leed auth login, with identical flags and identical behavior. It reports its own name — login, not auth.login — in its --json document, so a consumer can match the command line it actually ran.

leed site

Run these from your site folder — the one holding leed.config.json — or from raw-content/. The CLI searches those two levels and no further.

leed site itself declares three hidden options — -l, --location, -c, --customer and --ci — which exist so a CI build can point the CLI at a checkout without a leed.config.json. They read BUILD_SITE_LOCATION, BUILD_CUSTOMER and CI respectively, and are documented alongside every other variable the CLI reads on leed.config.json, files and environment.

leed schema

leed schema --json
leed schema --command site.list --json

The CLI describing itself: every command leaf with its argv path, its arguments, its options — inherited globals included, each tagged with the command that declares it — and the JSON Schema of the documents it can answer with. It is built from the live command tree of the binary running it, so it cannot describe a version other than the one you have. --command accepts either spelling of a name, dotted (site.list) or as an argv path (site list). It is the reference for anyone scripting leed, and it is documented under discovering the CLI.

Maintenance commands

leed self-update

Checks the registry for a newer release and installs it, bypassing the 24-hour throttle the automatic check obeys. With nothing to do it prints “Already up-to-date, no updates required.”; otherwise it prints “Update complete!” once bun install -g has finished. The automatic update path — which installs rather than merely notifying, and how to suppress it in a script — is described under installing the Leed CLI.

leed completion install
leed completion uninstall

Shell tab completion for bash, zsh and fish, detected from SHELL. The candidate list is generated from the live command tree, so it never goes stale as commands and flags change. Install prints “Shell completion installed. Restart your terminal to activate.” Both commands are hidden from --help and both are fully supported.

Commands you will not run yourself

leed site upload and leed site notify-cms exist for the build pipeline. upload uploads a built worker version and reports the build result back to the CMS; notify-cms posts a committed change set to POST /api/site/pushed, and is what leed site push calls in-process at the end of a successful push. upload also works locally if you have a reason to run it. Both exit 2 when configuration or credentials are missing, which is one of the several places the CLI’s exit codes do not follow a simple 0/1 pattern — see CLI troubleshooting and exit codes for the full table.

completion-server is invoked by the shell hook that leed completion install writes, on every Tab press. It is the one command outside the --json envelope contract: its stdout is the shell’s candidate list, in a format the shell defines, whatever --json or LEED_JSON say.

Quick reference

Every command that appears in --help, in one place.

Workflow context for these commands is in local development and validate, commit and push; if a command has failed and you are here looking for the message, start at CLI troubleshooting and exit codes.