Step-by-step guide
A task-first walkthrough, organized by what you're trying to do. Every step is a command you can copy.
.env.local and secrets, dev certs, overrides, machine-specific
config, the local notes you don't commit — as a single encrypted
image per repo. dew complements Git; shared docs still live in Git, and dew
never touches your tracked source.
Before you start
Install dew (once per machine):
brew install --cask vedanta/dew/dew # macOS — or grab a binary from the releases page dew version # confirm it's installed
Create your identity (once per machine — the key that encrypts and decrypts your images):
dew keygen # writes ~/.dew/identity.age.key — guard it like any private key dew key status # shows your public key
keygen again.
Scenario 1 — One machine
Goal: capture the gitignored files a repo needs into one encrypted image — to restore them after an accidental delete, or to get ready to go multi-machine.
cd my-app dew init # 1. create .dew/manifest.yaml in the repo dew scan # 2. see which local files dew suggests tracking dew add .env.local certs/ # 3. track specific files (or 'dew add .' for the suggestions) dew list # 4. review what's tracked ('dew rules' shows deny rules too) dew pack # 5. build the encrypted image at ~/.dew/images/my-app.dew.age git add .dew/manifest.yaml # 6. commit the manifest (paths only — no secrets) git commit -m "Add dew manifest"
After you edit a tracked file, just re-run dew pack — you declare files once and never re-add. To bring files back (e.g. after deleting one):
dew restore # writes the tracked files back into the repo dew restore --dry-run # preview first — change nothing dew doctor # checks the repo and reports the next step
Scenario 2 — Two machines
Goal: you packed on machine A; now hydrate the same local files on machine B (a new laptop, a dev server, …).
On machine A (the source) — publish
dew remote set nas:/volume1/dew # 1. where images sync — a local path or scp-style host:path dew remote test # 2. check it's reachable & writable dew sync # 3. push the encrypted image to the destination git push # 4. push the repo (with the committed .dew/manifest.yaml)
Bring your identity to machine B (one-time)
dew never moves your key automatically — you provision it explicitly, over SSH, to a machine you control:
dew key push you@machineB # from A, push your identity to B… dew key pull you@machineA # …or run this ON B to pull it from A
dew keygen on machine B. That creates a
different identity that can't decrypt your images. Bring the existing one
over (above), or copy ~/.dew/identity.age.key by hand — the
.pub is optional, since dew derives it.
On machine B (the target) — hydrate
git clone <repo> && cd my-app # 1. the clone already has .dew/manifest.yaml dew remote set nas:/volume1/dew # 2. point at the same destination dew sync pull # 3. fetch the encrypted image dew restore # 4. write your local files into the repo dew doctor # 5. → Repository fully hydrated.
Machine B now has the same working tree as A.
dew restore says "encrypted to a different identity":
the key on B doesn't match the one that packed the image. Bring machine A's
~/.dew/identity.age.key over (via dew key push/pull),
and don't keygen on B.
Scenario 3 — More machines (advanced)
Goal: use dew across a few of your own trusted machines (laptop, desktop, a server).
Each new machine is just Scenario 2's bootstrap again — provision the identity, then clone → remote set → sync pull → restore:
dew key push you@machine3 # provision each new machine… dew key push you@machine4 dew key devices # …and see where your identity has been sent/received
PEER DIRECTION FINGERPRINT WHEN LABEL you@machine3 sent-to age1xdde… 2026-06-03T00:06:31Z - you@machine4 sent-to age1xdde… 2026-06-03T00:10:02Z -
dew key devices is a best-effort log, not a way to revoke a machine.
Fine for a handful of machines you control; not for teams or disposable/untrusted
machines.
Scenario 4 — Carry an image by hand (no sync destination)
Goal: move a repo's local files from machine A to machine B without configuring any sync destination — copy the encrypted image yourself (scp, USB stick, a shared drive) and restore straight from the file.
On machine A — pack and copy
dew pack # 1. build the image as usual dew images # 2. shows the path: ~/.dew/images/my-app.dew.age scp ~/.dew/images/my-app.dew.age you@machineB:~/ # 3. move it any way you like
The image is age-encrypted end to end — safe to carry through untrusted channels; only your identity can open it.
On machine B — restore from the file
Your identity must be on B first (Scenario 2's bootstrap: dew key push/pull — and don't keygen on B):
git clone <repo> && cd my-app # 1. same repo, freshly cloned dew restore --image ~/my-app.dew.age --dry-run # 2. preview what lands where dew restore --image ~/my-app.dew.age # 3. hydrate from the carried file
--image needs no manifest and no sync destination — the file defines what it holds, and the usual safety rules apply (staged writes, conflicts left untouched without --force). If B becomes a daily driver for this repo, move the file into place instead — mv ~/my-app.dew.age ~/.dew/images/ — and plain restore/pack/sync work from then on.
Variant — carry the repo's entire local half
dew pack --all sweeps every local file — everything Git doesn't carry, ignored and not-yet-committed alike — into the image for that one run. The allow-list and manifest are untouched, the deny-list still drops generated noise (node_modules/, .next/, coverage/, …), and .git/ is never included. Git moves the shared half via clone; --all moves everything else (it asks git ls-files, so it needs a git repo):
dew pack --all --dry-run # preview the local file list first dew pack --all # then copy + restore on B exactly as above
pack --all overwrites the curated image
until your next plain dew pack — use it when moving machines, not as the daily flow.
Quick reference
| Do this | Command |
|---|---|
| Create your identity (once per machine) | dew keygen |
| Set up a repo | dew init |
| See / choose local files to track | dew scan · dew add <path> · dew add . |
| Review what's tracked / why | dew list · dew rules |
| Build the encrypted image | dew pack (--dry-run to preview) |
| Pack the repo's whole local half, one-shot | dew pack --all (everything Git doesn't carry; deny-filtered) |
| Set / check the sync destination | dew remote set <dest> · dew remote test |
| Push / fetch the image | dew sync · dew sync pull |
| Restore your local files | dew restore (alias dew hydrate) |
| Restore from a hand-carried file | dew restore --image <file.dew.age> |
| Move your identity to another machine | dew key push <user@host> · dew key pull <user@host> |
| See where your identity has gone | dew key devices |
| Check health / next step | dew status · dew doctor |
| List images you manage | dew images · dew remote images |
Troubleshooting
| Symptom | Fix |
|---|---|
no identity found | dew keygen (or bring your key over with dew key push/pull) |
no manifest found | dew init |
encrypted to a different identity | Bring the same key the image was packed with; don't keygen on a new machine |
Hydration: Incomplete / files missing | dew sync pull then dew restore |
no destination configured | dew remote set <dest> |
required tool "scp"/"ssh" not found | Install OpenSSH, or use a local/mounted destination |
Run dew doctor first whenever a clone isn't working — it names the one thing to fix next. For the full reference, see the user manual and command reference.