Frequently asked questions

dew is a local-first CLI for the private, local files that make a cloned repository actually work — the files Git usually ignores on purpose. Examples include .env.local, development certificates, docker-compose.override.yml, private fixtures, local notes, machine-specific config, and sandbox credentials.

Git gives you the shared code. dew gives you the missing local context.

A Git repo often does not contain everything needed to run the project locally. That is usually intentional — you do not want to commit secrets, private config, certificates, or machine-specific overrides. But the result is familiar:

git clone <repo>
cd <repo>
npm install
docker compose up
# ...and then something breaks because local files are missing

dew solves the "fresh clone is not really runnable" problem by letting you package selected local-only files into an encrypted image and restore them later.

dew uses a two-location model. In your repo it stores a committed manifest at .dew/manifest.yaml — metadata only, saying which local files dew should manage. In your home directory it stores private local state under ~/.dew/:

~/.dew/config.yaml
~/.dew/identity.age.key
~/.dew/identity.age.pub
~/.dew/images/<project>.dew.age

The basic flow is:

dew keygen
dew init
dew add .env.local
dew pack
dew remote set <destination>
dew sync

On another machine:

dew key pull <user@host>
dew remote set <destination>
dew sync pull
dew restore

The encrypted image is the packed form of your allow-listed local files. The pipeline is:

allow-listed files -> tar -> zstd compression -> age encryption -> .dew.age image

The result is stored locally under ~/.dew/images/<project>.dew.age. This is the file that dew sync copies.

The manifest is the repo-level contract for dew. It lives at .dew/manifest.yaml and usually contains:

version: 1
project: myrepo
image: myrepo.dew.age
id: 1234567890abcdef1234567890abcdef
allow:
  - .env.local
  - docker-compose.override.yml
  - certs/
deny:
  - "*.log"
  - tmp/

The manifest is safe to commit because it contains file names and rules, not the file contents.

Because the manifest describes the repo's expected local context. A new clone needs to know what files are managed by dew, what image name to look for, what should be restored, and what should be ignored even inside allow-listed directories.

The manifest is shared project metadata. The actual private files are not.

.gitignore is useful input, but it is not the source of truth — dew's source of truth is the manifest allow-list. dew does not blindly pack "everything ignored by Git." Instead, you explicitly choose what dew manages:

dew add .env.local
dew add docker-compose.override.yml
dew add certs/

The allow-list is authoritative. (The one deliberate exception is dew pack --all, which packs all local files — everything Git doesn't carry — for that single run; the deny list still applies, and the manifest is untouched.)

The deny list prevents noisy or unsafe files from being packed, especially when you allow-list a directory. For example, after dew add local/ you may still want to exclude *.log, tmp/, or node_modules/. dew uses three deny layers:

1. built-in deny patterns
2. global deny rules in ~/.dew/config.yaml
3. repo deny rules in .dew/manifest.yaml

Layers are evaluated built-in → global → repo with the last matching rule winning, and lines support gitignore-style ! negation — so a repo can override a global or built-in rule (e.g. deny: ["!keep.log"]). A file you dew add by name is always packed regardless. The built-in layer is deliberately minimal — universal noise only; project-specific exclusions go in a repo deny (below). Inspect the effective rules with dew rules.

Because it isn't universal. dew's built-in deny list only covers paths regenerated in essentially every project that has them — node_modules/, Pods/, .gradle/, and so on. A directory that's throwaway output in one project is hand-written source in another: an Expo app regenerates ios/ and android/ with expo prebuild, but a bare React Native app keeps real source there. dew can't tell them apart (Git shows both as untracked), and guessing wrong would silently drop someone's source.

So exclude project-specific generated files with a repo deny in .dew/manifest.yaml:

deny:
  - "packages/mobile/ios/"
  - "packages/mobile/android/"

This keeps the built-in list small and predictable and puts project knowledge in the repo. dew pack --all --dry-run shows exactly what an image would include, so you can see what to trim.

No. dew does not provide secret leasing, rotation, access policies, audit trails, approval workflows, cloud IAM integration, or per-environment secret distribution. It is closer to a repo-aware local context manager.

It helps you preserve and restore files that already exist on your machine. Some of those files may contain secrets, but dew is not trying to replace tools like 1Password, Bitwarden, Vault, AWS Secrets Manager, Doppler, SOPS, or direnv.

Use a real secrets manager when you need team-wide policy, rotation, centralized access control, audit, and production-grade governance. Use dew when you need your private local repo context to survive across clones and machines.

No. By default dew only manages files that you explicitly allow-list in a repo manifest. It does not back up your whole home directory, your Git history, your IDE, your database, or arbitrary machine state — and it never packs content Git already carries. (dew pack --all can sweep one repo's entire local half — everything Git doesn't carry — into an image as a one-shot, for moving machines; still not a backup strategy.)

dew creates one encrypted image per repo. That image can be synced somewhere else, but dew does not replace a real backup strategy.

Think of dew as "the small missing local layer for this repo" — not "a complete backup system for my computer."

No. dew can copy encrypted images to a configured destination, but it is not a cloud storage provider — it does not host your files, run a server, give you an account, or manage a hosted backend.

You choose where encrypted images go: a NAS, another machine over SSH, a mounted drive, or a shared local path. dew moves encrypted images. It does not move your private key during normal sync.

No. The only repo file dew commits is the manifest, which describes paths and rules. The file contents are packed into an encrypted image stored outside the repo under ~/.dew/images.

That said, if you manually add secret files to Git, dew cannot protect you from that. Keep your .gitignore sane and review commits before pushing.

You should commit .env.example — but it does not solve the whole problem. An example file documents expected variables; it does not preserve your actual local values, dev credentials, certificates, private fixtures, or machine-specific overrides.

.env.example     -> committed documentation
.env.local       -> private local file managed by dew

Use both.

git-crypt is a good tool for a different workflow: encrypted secret files live inside the Git repo and are versioned in history. dew takes a different stance — Git tracks shared code and metadata, while dew manages private local files outside Git, with only the manifest in the repo.

Use git-crypt when you want encrypted files as part of repository history. Use dew when you want the repo to stay clean while still restoring local-only context after a clone.

SOPS is excellent for encrypting structured secret files (YAML, JSON, ENV, Kubernetes workflows) that you want versioned, reviewed, and deployed as part of infrastructure. dew is not trying to replace it.

dew fits better for local-only repo files that should not live in Git at all, even encrypted: dev-only certificates, local Docker overrides, private fixtures, a personal .env.local, local notes, and machine-specific app config.

You should use a password manager for credentials — but password managers usually do not restore a full repo-local working state. They can store the value of DATABASE_URL, but they do not naturally restore files like .env.local, docker-compose.override.yml, certs/dev.pem, or private fixtures.

dew is file-oriented; password managers are secret-record-oriented. They work together: keep your most important credentials in a password manager, and use dew for local repo context files that need to exist on disk.

direnv is great for loading environment variables when you enter a directory. dew solves a different problem: direnv activates local environment state, while dew preserves and restores local files. They complement each other:

.envrc        -> committed or local direnv config
.env.local    -> private values managed by dew

Those tools are for runtime environments — they help applications access secrets while running. dew is for local developer repo context: it helps a developer restore the local files needed before they can even run the app.

Git LFS is for large files that still belong to the repository (assets, binaries, datasets that are part of the project). dew is for local-only files that should not be committed at all: private local config, secrets, dev certs, and local overrides intentionally ignored by Git.

A dotfiles repo manages user-level configuration across machines ("how do I configure my shell/editor/system?"). dew manages repo-specific local context ("how do I make this cloned repo locally runnable again?"). They are complementary.

Manual copying works until it does not — it is easy to forget, hard to audit, inconsistent across machines, and unclear to future-you. dew gives you an explicit allow-list, repeatable pack/restore commands, encryption, repo-aware metadata, syncable images, and status/doctor checks.

It turns "I think I copied the right files" into a repeatable workflow.

dew stores the private age identity locally at ~/.dew/identity.age.key, with the public key at ~/.dew/identity.age.pub. The private key is what decrypts your images — protect it like any other private key.

No. dew sync moves encrypted images only — it does not copy ~/.dew/identity.age.key. That is intentional: if a remote destination is compromised, the attacker should only get encrypted images, not the key needed to decrypt them.

To move your identity to another machine, use the explicit key-transfer commands, which are deliberately separate from sync:

dew key push <user@host>
dew key pull <user@host>

If you lose the private key, you cannot decrypt images encrypted to that identity, and dew cannot recover them — that is the point of encryption.

dew deliberately stays out of key management, so treat ~/.dew/identity.age.key as sensitive material and back it up carefully yourself — a password manager, encrypted drive, or other secure storage.

There is no built-in rotation command — key rotation is intentionally out of dew's scope. dew uses one global identity for images. If you need to rotate manually, the safe path is:

1. restore files with the old key
2. generate or install a new identity
3. repack images with the new identity
4. resync images
5. update other machines carefully

If you need managed rotation, lease, and revocation, that is what a real secrets manager is for.

You will create a different identity that cannot decrypt images encrypted to your old identity. If you are setting up a second machine, do not run dew keygen unless you intentionally want a separate identity. Instead bring the existing key over:

dew key pull <user@host>   # on the new machine, from one that has the key
dew key push <user@host>   # or push to the new machine from one that has it

Run dew pack after you create or change files that dew manages:

vim .env.local
dew pack
dew sync

Think of dew pack as "capture my current local repo context into the encrypted image."

Run dew sync after dew pack when you want to copy the encrypted image to your configured destination.

dew pack          # source machine
dew sync

dew sync pull     # new machine
dew restore

dew hydrate is an alias for dew restore. It exists because "hydrate a clone" is the product idea: take a fresh repo clone and restore the missing local context. These are equivalent:

dew restore
dew hydrate

Not by default. If a local file already exists and differs from the image, dew reports a conflict and leaves the local file untouched. To overwrite local differences you must pass --force; use --dry-run to preview first:

dew restore --dry-run    # preview — change nothing
dew restore --force      # overwrite conflicting files

dew doctor checks the current repo and tells you what to fix next. It can detect a missing identity, missing or empty manifest, missing image, an image encrypted to a different identity, a corrupt/undecryptable image, and tracked files missing from the working tree. Use it when a clone does not work and you are not sure why.

dew status gives a quick health summary for the current repo: whether you have an identity, a manifest, an image, tracked files, the hydration state, and a sync destination. Use dew doctor when you want diagnosis and next steps.

dew images lists encrypted images managed by dew across all repos. It runs from anywhere because images live globally under ~/.dew/images. Use it to see what dew has packed on this machine.

dew clean removes dew's footprint for the current repo — the manifest, the local encrypted image, or both:

dew clean
dew clean --image-only
dew clean --manifest-only

It does not remove your global identity key.

dew does not compare the working tree against the image — image diffing is intentionally out of scope, and dew keeps no version history to diff against. The practical habit is to repack whenever you touch a dew-managed file:

dew pack
dew sync

dew status will also tell you whether the repo looks hydrated, and dew restore --dry-run previews how the image differs from what is on disk.

On the machine where the repo already works:

dew keygen
dew init
dew add .env.local
dew add docker-compose.override.yml
dew pack
dew remote set <destination>
dew sync
git add .dew/manifest.yaml
git commit -m "Add dew manifest"
git push

On a new machine:

git clone <repo>
cd <repo>
dew key pull <user@host>
dew remote set <destination>
dew sync pull
dew restore
dew doctor

Good candidates are local-only files needed to run the repo: .env.local, .env.development.local, docker-compose.override.yml, certs/, .local/, fixtures/private/, sandbox-config.yaml, dev notes.

Bad candidates: node_modules/, dist/, build/, target/, .git/, large database dumps, general downloads, files that should be in Git, and production secrets that belong in a secrets manager.

If the file is needed to make this repo work locally, should not be committed, and is small enough to carry, it may be a good dew candidate.

Usually, no. dew is primarily for local developer context. Production secrets should live in production-grade secret management systems with access control, audit, rotation, and deployment integration. dew can technically package any allow-listed file, but that does not mean every secret belongs in dew.

It can, but be careful. dew compresses and encrypts images, but it is not designed as a large-artifact manager or general backup system. Avoid using dew for database dumps, videos, model files, build artifacts, dependency directories, or generated outputs — use Git LFS, artifact storage, object storage, or backups for those.

dew packages files through a tar archive and restores regular files; file permissions are preserved where practical. It is not a full filesystem snapshot tool, though — it skips symlinks and special files by design. If a workflow depends on exact ownership, ACLs, extended attributes, or platform-specific metadata, dew may not be the right layer.

No. dew skips symlinks and special files when building the archive. This is intentional — symlinks can create confusing and unsafe restore behavior. dew is designed around regular files and directories.

Commit the manifest:

.dew/manifest.yaml

Do not commit ~/.dew/, the identity key, the encrypted images, or the actual private files (.env.local, private certs, local overrides). Your .gitignore should continue ignoring the real local files.

No. The manifest is meant to be committed. The local encrypted images and identity are stored outside the repo under ~/.dew/, so they should not appear in normal repo status anyway.

Both, but it is especially useful for solo developers and small teams. Solo developers use dew to move between laptops, desktops, dev boxes, and fresh clones. Small teams can commit a shared .dew/manifest.yaml so everyone agrees on which local files are needed, while each developer keeps their own encrypted image and identity.

For larger teams, use dew carefully — it does not replace enterprise secrets management, access control, or audit tooling.

Yes. The manifest can be committed to Git and shared by the team. Each developer can have their own private local files and their own encrypted image — the manifest tells dew what types of files matter for the repo, while the actual contents remain private.

Not necessarily. The simplest model is one encrypted image per repo per identity. For a team, each developer may maintain their own image because their local values may differ. dew is not a multi-user secret distribution system, and intentionally so.

Only if they also have the private key that can decrypt it. By default, images are encrypted to your dew identity, so anyone with the image and the private key can read the contents. For teams, think carefully before sharing a single identity — dew does not provide per-user access controls or revocation; for that, use a real secrets manager.

dew is centered around one image per repo/project. For more advanced environment-specific workflows you can use different project names or manifests, but be careful — dew is intentionally simple. If you need formal dev/staging/prod separation, use a real secrets manager.

Yes. dew does not care whether the Git repo is public or private — the manifest can be committed to either, and the sensitive file contents live outside the repo in encrypted images.

Yes, and that is one of the useful cases. A public repo can include a .dew/manifest.yaml that documents the local files needed for development without exposing the private contents:

allow:
  - .env.local
  - docker-compose.override.yml

The actual .env.local file remains private.

No. If a repo has a .dew/manifest.yaml, developers who do not use dew can ignore it — the manifest is just metadata and does not affect normal Git usage. Developers who want automatic local-context restore can install dew.

The image is encrypted, so it is designed to be safe to store outside your machine. But "encrypted" does not mean "careless." A good posture: keep the private key off the remote, use trusted storage, restrict access where possible, avoid syncing files you do not need, and rotate credentials if you suspect exposure. dew protects image contents with encryption; it does not provide cloud access control, audit, or key management.

Yes. The image is one encrypted file — copy it however you like (scp, USB stick, a shared drive), then restore straight from it on the other machine:

# machine A
dew pack
scp ~/.dew/images/my-app.dew.age you@machineB:~/

# machine B (in the cloned repo; your identity already there)
dew restore --image ~/my-app.dew.age

--image needs no manifest and no sync destination; the usual non-destructive restore rules apply. If the machine will keep using dew for that repo, move the file into ~/.dew/images/ instead so plain restore/pack/sync work from then on.

dew keeps this simple by design: the workflow focuses on packing, restoring, status, and doctor checks rather than a separate image browser. Use dew restore --dry-run to preview what a restore would write, change, or flag as a conflict — without touching the working tree.

No. Archive extraction is designed to reject absolute paths and path traversal, so an image cannot write outside the target repo during restore. This is a core safety behavior.

dew uses image-ownership metadata to avoid accidental collisions. If two repos use the same project/image name, dew avoids overwriting an image created by a different repo unless you explicitly force the operation. If you see this warning, use a unique project name:

dew init --project <unique-name>

Treat the sync destination as storage for encrypted images — it does not need your private key, which is the important boundary. Still, use a destination you control or trust: an attacker who can tamper with images can cause denial-of-service or confusion, even if they cannot decrypt the contents. Run dew doctor after pulling if something seems wrong.

The basic model:

• The repo manifest is public/shareable metadata.
• The encrypted image contains private file contents.
• The private key stays on machines you control.
• Sync moves encrypted images, not keys.
• Restore is local and explicit.
• Key transfer is explicit and separate.

dew protects against accidental Git commits of local context by keeping contents outside the repo, and protects synced images with encryption. It does not protect against malware on your machine, someone with access to your private key, secrets already committed to Git, weak remote access controls, lack of key rotation, or production secret-governance requirements.

Use this checklist:

dew scan
dew add <specific-files>
dew rules
dew pack --dry-run
dew pack
dew restore --dry-run
dew doctor

Also review git status and git diff --cached to make sure you are committing only the manifest, not the private files themselves.

Usually dew is more useful for local development than CI/CD. CI/CD should use proper secret injection from the CI system, cloud secret manager, or deployment platform. Some internal workflows might use dew to hydrate test fixtures or local-like environments, but that should be done carefully and intentionally.

dew is designed as a single binary for macOS, Linux, and Windows. Be aware that path handling, file permissions, SSH availability, and shell behavior can vary by platform — if your team is cross-platform, test your actual workflow on the platforms you support.

dew is useful today for local development workflows, especially for solo developers and small teams. For production secret management, enterprise access control, compliance, auditing, and key rotation, use specialized tools.

Production-grade idea for local developer context. Not a production secrets platform.

Git should hold the shared code and shared project truth. But every working repo also has a local half: private config, dev certs, local overrides, fixture data, and notes that make the clone usable. That local half is real — it just does not belong in Git.

dew gives that local half a clean, encrypted, repeatable home.