Set up
ezc setup --new-local # a new store on this machine
ezc setup --new-github owner/repo # a new store, and a private GitHub repo for it (needs gh)
ezc setup --store owner/repo # an existing store: owner/repo (needs gh), a URL or a path
ezc setup --ci --store owner/repo # in a CI job: see "Bots and CI"
ezc setup takes a machine from nothing to a working store. It checks that git and sops are installed (and offers to install sops with Homebrew when brew is there; otherwise it says how to install it and stops, with nothing made), creates your key, creates or clones the store, and writes config.toml in ezc’s home ($EZC_HOME when set, else ~/Library/ezc on macOS and ~/.local/share/ezc on Linux). The store is a git repo at store in that folder. On a terminal with no store and no flag at all, setup opens the setup wizard, which asks what to do and runs setup (or ezc join) with the flags it gathered. With some flags, setup asks on the terminal for what they leave out: your name, where the store comes from, and whether to install with brew; --name and --yes answer in advance. Without a terminal it needs one of the three flags above.
Each line it prints is something that was already there (✓) or something it made (+). It ends with the command to run next when the store can take a secret, that is when it has an encryption policy. A new key is written to ~/.config/sops/age/keys.txt (or the key_file of config.toml, or the file SOPS_AGE_KEY_FILE names), readable only by you. Back that file up when setup says so: without it your secrets cannot be read, and it cannot be recovered. Setup never prints the private key.
Setup does not touch Claude Code’s folder. ezc’s agent skill ezc-convert, which moves a repo from .env files or hard-coded values to a manifest and .ezc/, is in this repo at cli/share/skills/ezc-convert. To use it, copy the folder to skills/<name>/ under $CLAUDE_CONFIG_DIR, or ~/.claude when that is not set.
A new store starts with an empty manifest, recipients.yaml naming you and your public key, the encryption policy written from it, and one commit. Your name is --name, else the user of config.toml, else your login name ($USER) in lower case; it is lower case letters, digits and -, starting with a letter or a digit. When none of these gives one, setup stops and asks for --name.
--store a/b always means the GitHub repo a/b; for a folder of that shape write ./a/b. After --store, when your key is not one the store’s recipients.yaml names, setup says so and prints your public key: give it to someone who has access, who adds it with ezc user add (see Access). The machine is set up either way, and ezc doctor reports the missing access as a problem until it is given. To use the key of another machine of yours, put its key file in place before you run setup.
Run again, setup changes only what is missing. A key file, a store or a value in config.toml that is already there is never overwritten, and a store with no remote is published by --new-github. Asking for a different store than the one in place is refused: move the store away first. Setup manages the store in ezc’s home, so it refuses to run while EZC_STORE is set.
A store made by hand, a folder with a .ezc/ that is already at the store’s path, is adopted: setup adds what it lacks and rewrites nothing that is there, so the manifest, the values files and a policy you wrote keep their bytes. A folder that is not a git repo becomes one, with its .ezc/ in one commit (+ made the store a git repo: <store>, commit setup: adopt the store); after that every write is committed and --new-github can publish it. A .ezc/ with no manifest.yaml gets an empty one (+ wrote an empty manifest). A store with neither recipients.yaml nor an encryption policy gets both, naming you (+ wrote the registry and the encryption policy), but only when it holds no encrypted values file: one that does was set up by someone, under a policy that is not in its .ezc/ (at the top of the repo, say), so setup writes neither and says ! This store holds encrypted values but has no recipients.yaml and no encryption policy in .ezc, so ezc does not manage who can read it. A store with recipients.yaml and no policy gets the policy written from it. A store with a policy and no recipients.yaml is left as it is, because the policy was written by hand and setup will not replace it: setup says ! This store's encryption policy was written by hand and it has no recipients.yaml, so ezc does not manage who can read it. Keep editing the policy by hand for now., and ezc doctor keeps its access warning. A store cloned with --store is treated the same way. When the store is a git repo that lacks something and git cannot say how it stands (it is not on a branch, as while a rebase is open), setup writes nothing and stops with what the write commands say: the store in <store> is not on a branch (a rebase may be in progress). Finish or abort it with git, then run this again. A store that EZC_STORE names is not adopted: setup does not run for it, and it keeps working as a plain folder.
Protect the store’s branch
A store on GitHub is as safe as its default branch. recipients.yaml, which says who can read the secrets, is a file on that branch, and every change to access re-wraps the secrets for everybody it names. So let only the store’s recipients push to the default branch: add a branch protection rule or a ruleset for it in the repo’s settings, with force pushes off. The ezc/join-* branches that ezc join pushes need no protection, because a request is never merged. Who can change the registry says what ezc itself reports when the registry changes.