Usage guide

Everything you can do with env-sync — from adding your first secret to managing peer access across machines.

Quick commands

The most common commands you will use day to day:

env-sync              # sync secrets from peers
env-sync status       # show current mode, host, peer count
env-sync discover     # list discovered peers on the network
env-sync --help       # full command reference

Desktop GUI

Prefer a visual workflow? Install env-sync-gui with --all or --gui-only and launch the desktop app alongside the CLI.

The GUI works on the same ~/.config/env-sync/ state as the CLI, so secrets, peers, keys, backups, and mode changes stay in sync whichever interface you use.

Inside the app, the dashboard gives you status at a glance, while dedicated views handle secrets, sync, peers, keys, settings, and logs. For the complete GUI guide, see GUI.md.

Mode management

Switch between security modes at any time. Mode switching is non-destructive by default.

env-sync mode get
env-sync mode set trusted-owner-ssh
env-sync mode set secure-peer
env-sync mode set dev-plaintext-http
env-sync mode set secure-peer --yes
env-sync mode set trusted-owner-ssh --prune-old-material --yes

Peer management

secure-peer mode — invitation-based access with explicit approval:

env-sync peer invite --expires 1h
env-sync peer request-access --to hostname.local --token <token>
env-sync peer list --pending
env-sync peer approve new-host.local
env-sync peer revoke compromised-host.local
env-sync peer trust show hostname.local

trusted-owner mode — any SSH-reachable peer can sync without approval.

Secret & sync operations

# manage secrets
env-sync add KEY="value"
env-sync remove KEY
env-sync list
env-sync show KEY
eval "$(env-sync load 2>/dev/null)"

# sync with peers
env-sync sync
env-sync sync hostname.local
env-sync sync --force-pull hostname.local
env-sync sync --dry-run

--force-pull fully overwrites local secrets from the selected host. A backup is created first.

Service, cron & backups

# background service
env-sync serve -d
env-sync service stop
env-sync service restart
env-sync service uninstall

# automatic sync via cron
env-sync cron --install --interval 30
env-sync cron --show
env-sync cron --remove

# restore from backup
env-sync restore       # list available backups
env-sync restore 1     # restore specific backup

Troubleshooting

# check the log file
tail -f ~/.config/env-sync/logs/env-sync.log

# verbose output
env-sync sync --verbose

# verify connectivity
env-sync discover