@jesstelford/devenv-bootstrap

One command. Fresh machine to working devenv shell.

npx @jesstelford/devenv-bootstrap

What it does

Run inside any directory:

1. Installs Lix (the Nix fork) if nix is missing.
2. Installs direnv and devenv via nix profile.
3. Adds the direnv hook to ~/.zshrc or ~/.bashrc (idempotent).
4. Writes ~/.config/direnv/direnv.toml with hide_env_diff = true to silence the long direnv: export +VAR1 +VAR2 ... summary on every load.
5. Installs a use_devenv_quiet helper into ~/.config/direnv/direnvrc (in a marker block — re-runs update it cleanly). The helper:
   • Streams full devenv progress on first build (so the terminal doesn't appear frozen during nix substitutions).
   • Stays quiet on cached loads (one summary line: direnv: devenv ready (logs: …)).
   • Captures all output to a per-project log under $TMPDIR.
   • Dumps the log + a FAILED line on build error.
6. If the current directory has no devenv.nix / devenv.yaml / .envrc, scaffolds minimal starters. Existing files are left alone (an existing .envrc is backed up to .envrc.bak only if it doesn't already use devenv_quiet).
7. Adds .devenv/, .devenv.flake.nix, .direnv/ to .gitignore if absent.
8. Runs direnv allow . for the current directory.
9. Prints commands to activate the env in the current shell (for agents/CI that can't open a new terminal).

Idempotent throughout. Re-running picks up new versions of the helper and skips anything already done.

Per-project files after bootstrap

A bootstrapped project contains:

devenv.nix       # your packages and shell hooks (the only project-specific file)
devenv.yaml      # input pinning (boilerplate)
devenv.lock      # generated by direnv allow / devenv shell — commit this
.envrc           # 4-line stub:
                 #   if ! command -v devenv &>/dev/null; then
                 #     echo "[setup] devenv not on PATH. Run: npx @jesstelford/devenv-bootstrap"
                 #     exit 1
                 #   fi
                 #   use devenv_quiet

No per-project setup script. The .envrc is the same one line in every project — the heavy lifting lives in the user-level direnvrc.

Activation

After running the bootstrap, either:

• Open a new terminal — the direnv hook is now in your shell rc, so cd into the project auto-activates it.
• Stay in the current shell (agent / CI workflows):

  . /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
  eval "$(direnv export zsh)"   # or bash

  The bootstrap prints these exact commands at the end of its run.

Output on each direnv load

direnv: loading ~/myproject/.envrc
direnv: devenv ready (logs: /var/folders/…/T/direnv-myproject.log)

Two lines. The full devenv chatter is in the log file if you want to inspect it; on build failure the log is dumped to your terminal automatically.

Re-running the bootstrap

Safe and useful:

• After upgrading the bootstrap (npx @jesstelford/devenv-bootstrap@latest), the marker block in ~/.config/direnv/direnvrc is rewritten with the latest helper.
• In a fresh project directory it scaffolds the missing files.
• In an already-bootstrapped project it's effectively a no-op except for direnv allow.

Requirements

• macOS (Darwin) or Linux
• A POSIX shell (zsh recommended; bash 3.2 on macOS auto-re-execs into zsh)
• Node 18+ if invoking via npx (not required if you fetch and run the script directly)

Sudo is needed only for the Lix install step on first run, and only if nix isn't already installed.

Direct (no-Node) install

curl -sSf https://raw.githubusercontent.com/jesstelford/devenv-bootstrap/main/lib/bootstrap.sh | bash

Why a separate tool?

A bootstrap script that lives inside a project repo can't do the machine-level work (writing your shell rc, your global direnvrc, your direnv.toml) without copy-paste between repos. Putting it in npx-shaped distribution means:

• Every devenv project's .envrc becomes the same four lines, not 50.
• Bug fixes and improvements to the quiet wrapper roll out to every project on the next bootstrap run, instead of being copy-pasted.
• New projects scaffold from npx instead of from a cookiecutter or template repo.

License

MIT