sites.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 site registry, how a command finds the site it works on, 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 things explains it.

sites.json

~/.config/leed/sites.json is the one per-user registry of the sites set up on this machine. leed site init records each site it sets up there, one entry per company and environment, and every later command run inside a checkout refreshes where that checkout is. It replaces the leed.config.json older CLIs kept beside each checkout. Nothing about a site has to sit outside its repository any more: a checkout identifies itself by its own identity.json, and the registry is a record of where each one was last seen.

{
  "version": 1,
  "sites": [
    {
      "companyId": "cmp_4a71",
      "environment": "production",
      "domain": "example.com",
      "companyName": "Example",
      "paths": ["/home/you/leed/example-com/raw-content"],
      "remote": "https://gitlab.com/leed-ai/customers/production/example-com/raw-content.git",
      "userId": "usr_1c8e",
      "initialized": true,
      "huskyVersion": "6.26.0"
    }
  ],
  "migratedFrom": ["/home/you/leed/example-com/leed.config.json"]
}

How a command finds its site

A site checkout is the nearest folder holding identity.json: the folder you are in, its raw-content/ when it has one, or the nearest folder above you. So every leed site command works from the site folder, from raw-content/, or from anywhere inside it, wherever you keep it:

leed/
└── example-com/                 <- run from here: ./raw-content is the checkout
    └── raw-content/             <- or here: identity.json is in this folder
        └── src/docs/            <- or anywhere below it

Moving or renaming the folder needs no action: the next command run inside it records the new path. Outside every checkout, a leed site command needs --site <name|domain|companyId> — the names leed site list shows — and moves into that site’s checkout before it runs. Without it, it refuses, listing the registered sites and the exact --site to pass, even when only one site is registered:

This is not a site checkout. Pass --site to name the site to work on. Registered sites:
  …

With no registered site at all, the refusal is “No Leed site found at or above <folder>.”, coded not_a_site_repo, with the hint to run the command inside your checkout, pass --site, or run leed site init. A checkout that is not registered — a bare clone, a sandbox — runs in direct mode: its company and environment come from its own identity.json.

The fields the CLI maintains

huskyVersion is the one drift marker left, and it is the reason hook files reappear in your repository after you upgrade. When you run any leed site command other than init, the CLI compares it against the version of the CLI that is running. When they differ it reinstalls the husky hooks and records the new version. Nothing asks first, and nothing is destroyed that the CLI did not put there. The VS Code files and Claude Code skills older CLIs kept in sync are no longer managed: leed site vscode writes the VS Code files when you ask, and the skills come from the Leed plugin for Claude.

paths and companyName are refreshed every time a command runs inside a checkout, so editing them by hand does nothing lasting.

Upgrading from leed.config.json

Older CLIs kept one leed.config.json per site, in the folder above the checkout, and the installer left one in ~/leed. Each such file the CLI meets — in the folder you are in, any folder above it, ~/leed, or a folder directly inside ~/leed — is imported into sites.json once, with a one-time notice, and its path is recorded in migratedFrom so it is never read again. The file itself is left in place and can be deleted. The vscodeVersion and aiConfiguration keys it carried are not imported, and the skill copies they recorded are removed from the checkout’s .claude/skills/.

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 are read and which CMS it talks to. Nothing defaults to production. The CLI never picks an environment, a company or a site you did not name, and the checkout you are standing in counts as naming one.

flowchart TD
  A["leed <command>"] --> B{"-e / --env passed?"}
  B -- "yes" --> R1["Use it"]
  B -- "no" --> S{"--site given?"}
  S -- "yes" --> R2["Use that site's environment"]
  S -- "no" --> C{"Inside a site checkout?"}
  C -- "yes" --> R3["Use the checkout's environment<br/>sites.json, else identity.json"]
  C -- "no" --> D{"ENV_NAME set<br/>and valid?"}
  D -- "yes" --> R4["Use it"]
  D -- "no" --> E{"--company logged in to<br/>exactly one environment?"}
  E -- "yes" --> R5["Use that environment"]
  E -- "no" --> R6["Refuse: invalid_arguments<br/>rerun with -e &lt;env&gt;"]

That one chain serves every command that takes an environment. On leed auth login, logout and leed asset upload the -e, --env flag is hidden from --help; leed setup, leed site, leed mcp add and the leed settings, page, deployments and contacts commands show it. On leed site, -e only chooses between two registered sites of the same company, since a leed site command always runs in a checkout. CLI authentication covers when you need it.

leed site push, commit and the hidden notify-cms and upload also refuse outright when nothing names an environment — a checkout whose identity.json names none, with ENV_NAME unset:

Could not determine the target environment. Run from inside a Leed site checkout (see leed site list) or set ENV_NAME=dev|staging|production.

The order 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 checkout, setting ENV_NAME does not redirect a push, an import or any other command. Pass -e where the command takes it, 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/auth.json            0600, in a 0700 directory
├── .config/leed/auth.json.lock       0600, present only while a command renews the session
├── .config/leed/sites.json           0600, the site registry
├── .config/leed/sites.json.lock      0600, present only while a command updates the registry
├── .config/leed/preferences.json     0600, offers you have answered once
└── .cache/leed/<env>/<companyId>/
    ├── leed-validation.json          what you validated, and your last build
    └── imports/<pageTypeId>.json     one resumable import manifest

leed/example-com/
├── example-com.code-workspace        only after leed site vscode, or a yes to leed setup's offer
└── raw-content/                      the git repository, and the site checkout
    ├── identity.json                 from the repository: which company and environment this is
    ├── .git/config                   credential-free origin, plus the leed credential helper
    ├── .husky/                       pre-commit, pre-push, commit-msg
    ├── .vscode/tasks.json            12 tasks, written with the workspace
    ├── 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 checkout with an identity.json that is not registered in sites.json, sandboxes included — the checkout is used as it is, its company comes from identity.json, and the customer is derived from the folder above it; CI never reads or writes sites.json. In managed mode, the ordinary case, the checkout’s sites.json entry is loaded. Passing both --customer and --location names the checkout outright, as <location>/<customer>/raw-content. 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:

Nothing here is unrecoverable from the CLI. If sites.json is lost or damaged, run leed setup --env <environment> again, or leed site init --company <companyId> -e <environment> --dir <the folder above your site folder>; either records the site again without touching your working tree. That path is described on installing the Leed CLI.

A corrupt auth.json is reported, not ignored: a file the CLI cannot parse stops the command with “The credential file … is unreadable.” rather than reading as “not logged in”, so the next login cannot silently overwrite it. Fix or remove it, then sign in again. A sites.json that is not JSON is set aside as sites.json.corrupt-<ms> on the next write rather than overwritten. An unreadable import manifest, by contrast, is still treated as “start over”.

The 600 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.