CLI Reference¶

Complete reference for all envsecrets commands.

Global Flags¶

Flag	Description
`--config`	Path to config file (default: `~/.envsecrets/config.yaml`)
`-r, --repo`	Override repository identifier (format: `owner/name`)
`-v, --verbose`	Enable verbose output
`--json`	Output in JSON format (for scripting)
`--non-interactive`	Disable interactive prompts (for CI/CD)

Commands¶

init¶

Create or update configuration interactively.

envsecrets init

status¶

Show repository info, file status, and a recommended next action.

envsecrets status

Displays repository name, bucket, remote HEAD with provenance (pushed by user@machine, Xm ago), this machine's last-synced commit, the status of each tracked file, and a Sync status block with one of these recommendations:

Recommendation	Meaning
In sync. Nothing to do.	Local working tree, last-synced baseline, and remote HEAD all agree.
Run `envsecrets push`	You have local edits not yet on remote.
Run `envsecrets pull`	Another machine pushed; you have no local edits.
Run `envsecrets pull` then `envsecrets push`	Both sides changed, but on different files (no overlap).
Reconcile	The same file changed on two machines. Use `envsecrets diff <file>`, then `envsecrets pull` (interactive), then `envsecrets push`.
Run `envsecrets push` to initialize the remote	Remote is empty; first push initializes it.
Run `envsecrets pull` first	This machine has no sync baseline yet (fresh clone, post-reset, or upgraded from an older client).

The recommendation is computed from a true 3-way comparison: working tree vs LAST_SYNCED baseline vs remote HEAD. Hash and content equality drive the decision; timestamps are used only for context.

sync¶

Run the recommended push/pull/reconcile action automatically.

envsecrets sync [flags]

Flag	Description
`-m, --message`	Commit message used when sync runs push
`--dry-run`	Show what would be done without doing it

sync looks at the same Sync status block status produces and:

In sync → exits 0 with "Already in sync."
Push → runs envsecrets push.
Pull → runs envsecrets pull.
Pull then push → runs pull, then push.
Reconcile → prints reconciliation guidance and exits 16 (ExitActionRequired). Does NOT auto-resolve overlapping conflicts; resolve manually with envsecrets pull (interactive) then re-run envsecrets sync or envsecrets push.
First push init → prints "Remote not initialized; run envsecrets push" and exits 16. sync will not initialize a remote on its own.

There is no --force on sync. To override the divergence safety check, run envsecrets push --force directly.

push¶

Encrypt and upload environment files.

envsecrets push [flags]

Flag	Description
`-m, --message`	Commit message
`--dry-run`	Show what would be pushed without pushing
`--force`	Override the divergence safety check
`--allow-missing`	Allow push with missing tracked files (for non-interactive mode)

Divergence safety¶

By default, push refuses with ErrDivergedHistory (exit code 4) when:

The remote has moved since this machine's last successful sync, and
At least one tracked file changed both locally and on remote.

The error lists the conflicting files and points at the resolution path. Run envsecrets pull (interactive resolver) to reconcile, then push. Or pass --force to push your working tree as-is, dropping the overlapping remote changes for those files (the previous content remains in history).

This check is distinct from optimistic locking, which catches a race during a single push window. Both layers are active.

If the post-push baseline marker write fails (rare — disk full, permission), the push still succeeds remotely but a Warning: is printed. Run envsecrets pull before the next push to repair the marker.

pull¶

Download and decrypt environment files.

envsecrets pull [flags]

Flag	Description
`--ref`	Pull a specific version (commit hash)
`--force`	Overwrite local files without confirmation
`--dry-run`	Show what would be pulled without pulling
`--skip-conflicts`	Skip conflicting files instead of aborting

Conflict detection¶

Pull uses a 3-way comparison (working tree vs LAST_SYNCED baseline vs remote) to decide per file:

No local changes, remote moved → overwrite without prompting (the natural catch-up case).
Local-only changes, remote unchanged for this file → preserve the local copy (push will publish it).
Both sides changed the same file → real conflict; prompt or use the --force / --skip-conflicts / per-file resolver.

When this machine has no LAST_SYNCED baseline yet (fresh clone, post-Reset, or upgraded from an older client), pull falls back to the historical pessimistic behavior: any working-tree disagreement is treated as a potential conflict requiring --force. Run envsecrets pull once to establish the baseline; subsequent catch-up pulls work without --force.

Interactive prompt choices: - [o]verwrite - Replace local file with remote version - [s]kip - Keep local file unchanged - [a]bort - Cancel the entire pull operation

pull --ref <hash> performs a historical checkout and intentionally does not update LAST_SYNCED — the baseline tracks "where this machine is relative to remote HEAD", not arbitrary historical positions.

log¶

Show commit history.

envsecrets log [flags]

Flag	Description
`-n`	Number of commits to show (default: 10)
`-v, --verbose`	Show file changes in each commit

diff¶

Show changes between versions using line-by-line comparison.

envsecrets diff [ref1] [ref2]

No args: Compare local files against latest remote (HEAD)
One ref: Compare local files against that ref
Two refs: Compare two refs against each other

Output uses +/- prefix for added/removed lines, similar to git diff.

revert¶

Restore files from a previous version.

envsecrets revert [ref]

Flag	Description
`--dry-run`	Show what would be reverted without reverting
`-p, --push`	Push reverted state as new commit
`-m, --message`	Commit message (used with --push)
`-y, --yes`	Skip confirmation prompt

If no ref is provided in interactive mode, you can pick from recent commits. In non-interactive mode, a ref is required.

list¶

List repositories or files in the bucket.

envsecrets list [repo]

Flag	Description
`--current`	List files in auto-detected current repository

Without arguments, lists all repositories. With a repo name, lists files in that repo. With --current, auto-detects the current repository from git remote.

Internal storage files (FORMAT, HEAD, objects.pack, refs) are filtered from output.

rm¶

Remove a file from tracking.

envsecrets rm <file>

Flag	Description
`--dry-run`	Show what would be removed without removing
`-y, --yes`	Skip confirmation prompt

delete¶

Delete an entire repository from GCS.

envsecrets delete <repo>

Flag	Description
`--yes-delete-permanently`	Confirm deletion in non-interactive mode
`--dry-run`	Show what would be deleted without deleting

Requires confirmation in interactive mode. This is also the remediation command for legacy repositories that lack a FORMAT version marker — delete the remote and re-push with the current version.

rotate-passphrase¶

Re-encrypt all repositories with a new passphrase.

envsecrets rotate-passphrase

Flag	Description
`--dry-run`	Show what would be rotated without rotating

verify¶

Test decryption across all repositories. Reports the storage format version and number of files verified per repo.

envsecrets verify

encode¶

Base64 encode a service account JSON file.

envsecrets encode <path>

Flag	Description
`--copy`	Copy to clipboard (macOS/Linux)

doctor¶

Verify configuration and connectivity.

envsecrets doctor [flags]

Flag	Description
`--fix`	Attempt to repair corrupted cache

Checks configuration, GCS connectivity, passphrase, encryption, git repo, cache health, and storage format version.

The --fix flag will: - Remove corrupted cache directories - Re-initialize git repositories in the cache - Clear orphaned lock files

completion¶

Generate shell completions.

envsecrets completion bash
envsecrets completion zsh
envsecrets completion fish

Exit Codes¶

Code	Meaning
0	Success
1	Not configured (config file missing or invalid)
2	Not in a git repository
3	No .envsecrets file found or no files tracked
4	Conflict between local and remote
5	Decryption failed (wrong passphrase or corrupted data)
6	Upload failed
7	Download failed
8	Invalid configuration
9	GCS error
10	Git error
11	User cancelled operation
12	Invalid arguments
13	File or repository not found
14	Permission denied
15	Version incompatible (storage FORMAT missing or unsupported)
16	User action required (e.g. `sync` reached a `reconcile` state)
99	Unknown error