leed.config.json, Files and Environment

This is the reference page for two questions: where did that come from and where did that go. It covers the project configuration file, the complete set of files the leed CLI writes on your machine, and every environment variable it reads. Nothing here is something you routinely edit — the value of knowing it is that when a command behaves unexpectedly, one of these three things explains it.

leed.config.json

leed.config.json is your site’s project configuration. The CMS generates it, the installer downloads it, and leed site init finalizes it. It identifies which company and which environment this checkout belongs to, and it records the versions of the files the CLI manages inside your repository.

{
  "environment": "production",
  "domain": "example.com",
  "companyId": "cmp_4a71",
  "location": "/home/you/leed",
  "userId": "usr_1c8e",
  "initialized": true,
  "huskyVersion": "4.106.0",
  "vscodeVersion": "4.106.0",
  "aiConfiguration": {
    "claude": {
      "skillsVersion": "4.106.0",
      "installedSkills": ["site-builder", "site-preview", "site-publish"]
    }
  }
}

Where the CLI looks for it

Exactly two places, in this order:

leed/                        <- run from here: ./leed.config.json is found
└── example.com/
    ├── leed.config.json
    ├── example.com.code-workspace
    └── raw-content/         <- run from here: ../leed.config.json is found

Nowhere else. From a third location — your home directory, a subfolder of raw-content/src/, anywhere outside the tree — every leed site command stops with:

Could not locate leed.config.json. Run this application from the directory where your repo exists.

There is one asymmetry worth knowing about. The leed auth commands do not load the config file the way leed site does; when they need a default environment they walk three levels — the current directory, its parent and its grandparent — so leed auth status can pick up your site’s environment from one level deeper than a leed site command would.

The fields the CLI maintains

Three of the fields above are drift markers, and they are the reason files reappear in your repository after you upgrade. When you run any leed site command other than init, the CLI compares huskyVersion, vscodeVersion and aiConfiguration.claude.skillsVersion against the version of the CLI that is running. Where they differ it reinstalls the husky hooks, the VS Code workspace and tasks, and the Claude Code skills, then rewrites leed.config.json with the new versions. Nothing asks first, and nothing is destroyed that the CLI did not put there. What gets installed is listed on leed site init.

location is the odd one out: it is filled in every time the file is loaded, from where you actually ran the command, and the value on disk is not consulted. Editing it does nothing.

How the environment is decided

Every command resolves one of production, staging or dev before it does anything else, and the answer decides which credentials block is read and which CMS it talks to. There are two resolvers, and they do not agree — which is deliberate, because the consequences of guessing wrong are not symmetrical.

flowchart TD
  A["leed &lt;command&gt;"] --> B{"leed auth,<br/>or leed site?"}
  B -- "leed auth login / logout" --> C{"--env passed?"}
  C -- "yes" --> R1["Use it"]
  C -- "no" --> D{"ENV_NAME set<br/>and valid?"}
  D -- "yes" --> R2["Use it"]
  D -- "no" --> E{"leed.config.json found<br/>in cwd, parent or<br/>grandparent?"}
  E -- "yes" --> R3["Use its environment"]
  E -- "no" --> R4["production"]
  B -- "leed site data commands" --> F{"leed.config.json<br/>environment present?"}
  F -- "yes" --> R5["Use it"]
  F -- "no" --> G{"ENV_NAME set<br/>and valid?"}
  G -- "yes" --> R6["Use it"]
  G -- "no" --> R7["Refuse:<br/>Could not determine the<br/>target environment."]

For leed auth login and leed auth logout the chain is --env → ENV_NAME → the config file → production. The -e, --env flag exists only on those two commands and is hidden from --help; CLI authentication covers when you need it.

For the leed site commands that talk to the CMS — push, commit, notify-cms, upload, import, create-page-type and list — the strict resolver runs instead. It reads the config file’s environment first, falls back to ENV_NAME, and then refuses rather than assuming anything:

Could not determine the target environment. Run from inside a leed-managed site
directory (leed.config.json) or set ENV_NAME=dev|staging|production.

The inversion is on purpose. A wrong-environment push is hard to detect after the fact, so the checkout you are standing in wins over an environment variable that might be left over from something else. The practical consequence: inside a site folder, setting ENV_NAME does not redirect a push or an import. Change environment in leed.config.json, or work from a checkout for the environment you mean.

Which CMS each environment is

LEED_CMS_URL beats all three and applies to every request the CLI makes. An unrecognized environment falls back to the production URL.

Everything the CLI writes to disk

Three groups: your home directory, your project, and your cache.

~
├── .config/leed/credentials.json     0600, in a 0700 directory
├── .bunfig.toml                      the @leed registry scope
└── .cache/leed/<env>/<companyId>/
    ├── leed-validation.json          what you validated, and your last build
    └── imports/<pageTypeId>.json     one resumable OpenAPI import manifest

leed/example.com/
├── leed.config.json
├── example.com.code-workspace
└── raw-content/                      the git repository
    ├── .git/config                   origin URL, containing a token
    ├── .husky/                       pre-commit, pre-push, commit-msg
    ├── .vscode/tasks.json            12 tasks
    ├── .claude/skills/               site-builder, site-preview, site-publish
    ├── src/                          your content and templates
    └── .build/                       build output; .build/site is the rendered site

The cache paths are keyed by environment and company because one person can belong to more than one company on one machine, and a validation record from a staging checkout must never satisfy a production commit. What is inside the repository itself, folder by folder, is mapped in your site repository.

Relocating with XDG

XDG_CONFIG_HOME moves the credentials directory; XDG_CACHE_HOME moves the caches. Both are read at the moment a path is needed, so setting either for a single command works.

Environment variables

Split into three groups, because most of these are not for you.

Ones you might set

Ones CI sets for you

These are set on the Cloudflare Builds trigger during provisioning, or injected by the build platform. You do not set them by hand, and setting them locally will make a command behave as though it were running in CI.

The hidden leed site options

leed site carries three options that are hidden from --help because they exist for Cloudflare Builds rather than for you: -l, --location <path> (bound to BUILD_SITE_LOCATION), -c, --customer <string> (bound to BUILD_CUSTOMER), and --ci (bound to CI). They select between three ways of working out where your files are. In direct mode — any CI signal, or a bare raw-content checkout with an identity.json and no reachable leed.config.json — the current directory is the content repository and the customer is derived from the folder above it. In local mode, the ordinary case, leed.config.json is loaded and the repository is <location>/<customer>/raw-content. Passing both --customer and --location states it explicitly. Everything else on the command tree is indexed at CLI command reference.

Passing --customer or --location also suppresses the automatic update check, which is a side effect worth knowing about rather than a feature to rely on.

Cleaning up

Most of what the CLI leaves on your machine is disposable. What each deletion costs:

If you lose leed.config.json, open the profile menu in the CMS, choose Developer Setup, and either download a fresh copy or re-run the one-line installer — it reuses your existing session, skips the prerequisites it already satisfied, and rewrites the file. That path is described on installing the Leed CLI.

A corrupt credentials.json behaves differently from a missing one in a way worth knowing: a file the CLI cannot parse reads as an empty file, so the symptom is “not logged in” rather than an error. The same is true of an import manifest, which is treated as “start over”.

The 500 KB validation ceiling that FILE_VALIDATION_MAX_SIZE overrides is one of several product limits that have nothing to do with your plan — they are collected in limits that are not plan limits, and the rule it enforces is on leed site validate, commit and push. Large files that genuinely belong on your site go through the asset pipeline instead of the repository — see static files and caching. When one of these paths or variables turns out to be the cause of a failure you are looking at, the message is in the catalog on CLI troubleshooting and exit codes.