Usage guide

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

Quick commands

The most common commands you will use day to day:

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

Desktop GUI

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

The GUI works on the same ~/.config/syncenv/ 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.

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

Peer management

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

syncenv peer invite --expires 1h
syncenv peer request alice@hostname.local <token>
syncenv peer list --pending
syncenv peer approve bob@new-host.local
syncenv peer revoke mallory@compromised-host.local
syncenv peer trust show alice@hostname.local

Peer IDs are per-user (user@host). Endpoints also accept an explicit port: alice@hostname.local:5740.

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

Secret & sync operations

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

# sync with peers
syncenv sync
syncenv sync alice@hostname.local
syncenv sync --force-pull alice@hostname.local
syncenv sync --dry-run

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

Service, cron & backups

# background service
syncenv serve -d
syncenv service stop
syncenv service restart
syncenv service uninstall

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

# restore from backup
syncenv restore       # list available backups
syncenv restore 1     # restore specific backup

Troubleshooting

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

# verbose output
syncenv sync --verbose

# verify connectivity
syncenv discover

syncenv status   # shows user@host peer IDs
# each OS user has their own server port (~/.config/syncenv/port)