Synopsis
Description
The bare capy command is the main sync loop. It authenticates you (if needed), fetches the remote values for the branch you’re on, and compares three sources: your local .env, the values pinned in keep.lock, and the remote.
If all three agree, Capy prints Everything is up to date! and stops. If anything differs, it prints a comparison table and asks what you want to do. Which choices you get depends on which sources differ - Commit and push all local values, Retrieve all pinned values, Retrieve all remote values, Individually resolve, and Continue working. Nothing is pushed unless you pick the commit action. Whichever you pick, if keep.lock ends up changed Capy commits it for you - set CAPY_NO_AUTOCOMMIT=1 to opt out.
On first run in a project, it interactively initializes the project - picking an org, picking or creating a project, encrypting your existing .env, and writing keep.lock.
See Syncing secrets for the full flow.
Options
capy --dry-run is not a safe preview in v0.9.1. The flag parses, but the sync runs exactly as it would without it: it can rewrite .env, update keep.lock, and push to the remote. If you only want to look, run the sync and pick Continue working at the prompt.
Examples
First-run behavior
On first run (no keep.lock in the project), Capy:
- Authenticates you, reusing an existing session if you have one and opening your browser to sign in if you don’t.
- Prompts for an organization (or creates one, which generates a seed phrase).
- Prompts for a project - New project, or one of the org’s existing ones. If the org has no projects yet, it just asks for a name.
- Asks what branch the project should start with:
development (the default) or a name you type.
- Asks you to confirm, then encrypts every value in your
.env and uploads the ciphertext.
- Writes a commented-out copy of your original
.env to .env.pre-capy.old (gitignored).
- Rewrites
.env with capy:… snippets and gitignores it.
- Commits only
keep.lock to git - a small versioning manifest with no keys or secret values. Set CAPY_NO_AUTOCOMMIT=1 to skip that commit.
- Installs
post-checkout and post-merge git hooks, which run capy status after branch switches and merges.
If you have no .env (or it holds no variables), Capy stops after writing keep.lock, updating .gitignore, and installing the hooks. It stages keep.lock but leaves the commit to you, and tells you to add secrets and run capy push. If you pick an existing project at step 3, Capy skips the branch prompt and pulls that project’s development branch into the directory instead - again staging keep.lock for you to commit.
Capy reinstalls the git hooks whenever a sync completes (it skips the reinstall if you pick Continue working), and the install is idempotent - so capy cleanup removes them only until the next time a sync finishes.
