LORRI(1)

📦 version 1.7.1, in nixpkgs unstable

💖 LORRI(1) — like, the lorri manual but make it make sense 💖

okay bestie, grab a strawberry 🍓 and sit down, because this is the General Commands Manual page for lorri and we're gonna go through it together. No cap.

✨ NAME ✨

lorri — it's a nix-shell replacement for project development. literally that's the whole vibe.

🦋 SYNOPSIS 🦋

lorri daemon [--extra-nix-options json]
lorri direnv [--shell-file shell.nix]
lorri info --shell-file shell.nix
lorri init
lorri self-upgrade [local <path> | canon | rolling-release]
lorri shell [--cached] [--shell-file shell.nix]

🌸 DESCRIPTION 🌸

So. lorri is a nix-shell replacement for project development, and the whole thing is built around fast direnv(1) integration so you get robust CLI integration and editor integration. chef's kiss.

Honestly, lorri is about experimenting with and improving your dev experience with Nix. The particular focus? Managing your project's external dependencies, editor integration, and quick feedback. 🔥

Here's the tea: lorri gives you a daemon that automatically builds your project environment whenever its nix files change, and the direnv(1) integration instantly loads that project environment — in your shell and in your editor. the way that just works? iconic.

lorri supports Linux and macOS. periodt.

This man page documents the available commands, but there are also setup and installation instructions which you can find on the project page: https://github.com/nix-community/lorri/. iykyk 💅

🎀 Subcommands 🎀

  • lorri daemon [--extra-nix-options json] — Start the lorri daemon. It is required for most other commands to function (yes, required, so don't skip her, she's the main character). The daemon keeps track of the projects watched and will rebuild whenever a dependency of your project's shell.nix file changes. This includes nix files, source files, as well as non-nix source files — like, for example, json files loaded via ‘builtins.fromJSON (builtins.readFile …)’.

The --extra-nix-options flag takes a json description of nix options to overwrite. Only a subset is supported. See ‘lorri daemon --help’ for a description of the supported options. 🫶

  • lorri direnv [--shell-file shell.nix] — Print a piece of direnv(1) bash code, intended to be sourced in the .envrc of your project. Source it by adding
eval "$(lorri direnv)"

to your project's .envrc. It will then cause direnv to reload your environment whenever lorri finishes a rebuild. obsessed. ✨

.shell.nix is the file built and watched by lorri. Use the --shell-file flag to overwrite the file name:

eval "$(lorri direnv --shell-file foo.nix)"

The path is relative to the location of your .envrc. (yes, relative, don't come for me 🙈)

  • lorri info --shell-file shell.nix — Show project information for the given shell file. that's it, that's the command 💜
  • lorri init — Bootstrap a lorri project. The following files are created if they do not exist yet:
    • shell.nix — Minimal nix shell file
    • .envrc — A direnv config with the lorri direnv call.
  • lorri self-upgrade [local <path> | canon | rolling-release] — Upgrade lorri to a newer version. This uses nix-env(1) internally, and will install the new lorri to your user profile. It is intended as a quick way to update to latest canon, or to try out a specific branch. ngl, pretty handy 🎀
    • local will use the lorri checkout in <path>.
    • canon will update to the canon branch of https://github.com/nix-community/lorri/.
    • rolling-release will update to the rolling-release branch of that repository. rolling-release is not updated any more, please use the official release from nixpkgs. ⚠️

If no argument is given, rolling-release is assumed. (even though, see above, bestie 😭)

  • lorri shell [--cached] [--shell-file shell.nix] — Open a project shell. This is essentially a beefed-up nix-shell(1), with the following improvements:
    • It will use your interactive shell instead of bash(1) (bash(1), fish(1) and zsh(1) are supported currently).
    • If given the --cached flag it will use the environment that lorri built most recently. This means the project shell starts up instantly, similar to lorri direnv. 🔥

--shell-file opens a shell for the given shell.nix instead of the one in the current directory.

  • direnv's ‘use nix’ — Built-in support for watching a nix file with direnv. It will block on the evaluation of the shell.nix. If a dependency of the shell.nix changes, direnv will not pick it up, so you have to manually add them to the watch list with watch_file. See direnv-stdlib(1). lowkey annoying but okay.
  • shadowenv(1) — In spirit an alternative to direnv(1), it defines a domain specific S-expression format, shadowlisp(5), to specify environment changes. In the future, we might want to provide a way to generate this format. 👀

⭐ SEE ALSO ⭐

direnv(1), direnv-stdlib(1), nix-instantiate(1), nix-shell(1), nix-store(1), shadowenv(1), shadowlisp(5)

(go read them, bestie, they're all right there 🫶)

💀 KNOWN ISSUES 💀

  • Source files referenced by Import from Derivation (IfD) are not picked up. So, for example, if you use the callCabal2nix function to convert your project's ‘.cabal’ file to a nix expression on the fly, and you change the ‘.cabal’ file, lorri will not notice. 😭 There is some discussion in https://github.com/target/lorri/issues/309 on how to solve this issue.

okay that's the whole page, you ate that 🍓💅 ngl this one's from the Debian crew, dated July 20, 2020, and yeah — it's the LORRI(1) page, exactly like you'd find it in the manual. mwah, bye bestie! 👑🌈

📦 where this page comes from