nu_scripts: a shared shelf of Nushell aliases, modules and menus

A collection, not a package

nu_scripts is a place to share Nushell scripts with each other. The contribution model is stated in one sentence: if you would like to share your scripts, fork this repository, and create a PR that adds it to the repo.

That is the whole model, and it is worth being precise about what it means. There is nothing to install. There is no package, no version, no dependency resolution, no release artefact. What the repository is, is a well organised collection of files that you copy into your own configuration or source from a checkout.

The top level of the repository shows how broad the collection is. There are `aliases/` and `abbreviations/`, two directories the collection keeps for command shortcuts. There is `modules/`, which is the structured version of a script, with a package definition format and a dedicated README of its own. There is `themes/` for the prompt and syntax colouring. There is `custom-menus/` and `custom-completions/`, which are the two extension points for the interactive experience.

And then there are the directories that are less obvious and arguably more interesting. `nu-hooks/` holds hook definitions, which is the mechanism for running something when a particular event happens in the shell. `benchmarks/` holds scripts for measuring shell operations, which is a nod to the performance work that makes a structured shell different from a text file of aliases. `example-config/` holds configuration examples, and `nu_101/` is described in the README as a beginner introduction to nushell concepts, which is a teaching track rather than a script.

There is also a `skills/` directory, which is a newer addition to the repository layout and suggests the project is being used as a source of structured instructions for coding agents as well as for people. The `sourced/` directory holds the scripts that came from outside the project, with `cool-oneliners/` and `nu_101/` under it.

The MIT licence and the last push on 2026-10-13 complete the picture.

The sections, and what each one is for

The README lists the sections, and each entry carries a short description where one is needed, which tells you which of them are collections and which are single files.

`aliases/` is the plain alias collection. `benchmarks/` is the performance scripts. `cool-oneliners/` is under `sourced/` and is a list of one-liners worth remembering. `custom-completions/` is a collection of custom completions for external commands, which is the mechanism for teaching the shell about arguments that the underlying program does not describe. `custom-menus/` is a collection of custom nushell menus, and a menu is a scripted list of choices, so this section is really a set of interactive pickers that people have written.

`example-config/` holds configuration examples, which is the most directly useful section for someone setting the shell up from scratch. `nu-hooks/` holds the hook definitions. `modules/` is the most substantial section and has its own README, linked from the main one.

`nu_101/` is described as a beginner introduction to nushell concepts, which is a strong signal about the project. The naming is deliberate and it is a bit of a joke, and the point of including it is that a community script collection that contains a beginner track is a collection that welcomes people who do not yet know the shell.

`prompt/` sits under `modules/`, and it points at the `modules/prompt/` directory, which suggests the prompt is implemented as a module rather than as a configuration snippet. That is the right place for it in a structured shell, since a module can hold logic rather than only settings.

`themes/` is the last one in the list, and it is the section with the most visible effect on the user's experience, since the theme determines how the prompt and the output look.

Running a script, and the difference between alias and module

There are two ways to run a Nushell script, and the difference between them is the difference between a macro and a package.

The first is to type `nu <script name>`, which runs the script in a fresh Nushell process. That is the isolated option, where nothing the script does affects your current session, and it is the right choice for a one-off or for something you do not trust to change your environment.

The second is to source it from within Nushell, with `source <script name>`. And here the documentation splits behaviour by what kind of script it is. If the script is just a bunch of commands it will run the script. If the script is a custom command it will load those custom commands into your current scope so you can run them like any other command.

That distinction is the whole design of the collection, and it explains why there are two separate directories. An `aliases/` file is a set of commands, so sourcing it runs it. A `modules/` entry is a custom command, so sourcing it installs the command into your scope and you then call it by name.

So a module is the richer form. It has a structure, it can take arguments, it can be composed, and it is what you write when a one-liner has grown into a procedure. The README's link to a dedicated readme in the modules directory makes sense in that light, because the format needs explaining and the aliases directory does not.

The `abbreviations/` directory is a third thing again, a shortcut mechanism kept alongside aliases, and its presence at the top level of the repository means the collection is tracking the shell's own evolution in how commands are abbreviated rather than only in what the commands do.

The tooling around the collection, and the directories nobody names

The top level contains a set of files and directories that are not in the section list, and they describe the machinery that keeps the collection working.

`toolkit.nu` at the root is the giveaway that this is a Nushell project maintained with Nushell tooling. A single script at the root that can be run with `nu toolkit.nu` is the conventional way to give a repository a set of maintenance commands, and it means the tasks of validating and releasing the scripts are themselves written in the language the scripts are written in.

The `make_release/` directory is the release machinery, and given the repository has no GitHub releases, it is likely the mechanism that produces one, probably driven from CI. The `needs-update/` directory suggests a marker for scripts that are known to need updating, which is how a collection tracks staleness without blocking contributions.

`stdlib-candidate-archive/` is a fascinating name and it says something about the relationship between this repository and Nushell itself. A script collection that is a candidate for inclusion in the standard library would have its accepted scripts moved to an archive directory, which is a governance mechanism for promoting community work into the core.

`typos.toml` at the root configures a spell checker, which for a repository of shell scripts written by many people is a sensible guard against the typos that would otherwise become permanent in a shared file. `CONTRIBUTING.md` is the document the README points to for how to test and validate changes before sending a pull request, and its existence alongside a `tests/` style workflow is what makes the collection reviewable rather than a dumping ground.

There is also `assets/` for images, `games/` for scripts that are games rather than tools, which tells you the community treats the repository as a place to try things, and `.github/` for the workflows.

The `LICENSE` is MIT, and the repository is not archived.

Where a shared script collection stops

There are limits to the model, and they are the usual ones for a community collection rather than a published package.

The first is that nothing here is versioned with anything. A script in the repository is whatever is in the branch at the moment you copy it, and there is no changelog for an individual alias and no way to say this version of my module is incompatible with your Nushell. The `needs-update/` directory is a community signal, not a guarantee.

The second is that sourcing a script runs it in your current session, and a script from a stranger is code. A module can define custom commands, override an existing name, and change how your shell behaves. The documentation does not warn about this and it does not need to, but it is the thing to be careful about, and the `nu <script name>` form is the cautious way to try something.

The third is that a collection accumulates cruft. Scripts written for an older version of the shell may not work with the current one, and nothing in the repository prevents that, because the language is evolving and the collection is not pinned to a release.

The alternative approaches are worth naming. A personal configuration file in your own dotfiles is better still for the scripts you actually use, because you control the version.

The difference in approach is between a curated collection and a managed dependency. nu_scripts is the former, and it earns its place by breadth and by the quality of the examples rather than by reliability, which is the right thing for a place to share and learn from, and the wrong thing for a production environment where a broken script is an incident.

For a contributor, the path is straightforward and the documentation supports it. Fork the repository, add the script in the section that fits it, and read CONTRIBUTING.md for how to test and validate before sending the pull request. The repository's own structure, with the toolkit script, the release directory and the update markers, shows that the maintainers take the mechanical side seriously.

Editorial conclusion

nu_scripts fits a Nushell user who wants proven aliases, menus and modules rather than writing their own, and a contributor who wants a concrete place to put a script. Skip it if you want an installable package, because there is nothing to install: the repository is a set of files you source or copy, and the individual scripts carry no versioning of their own. Before you adopt anything from it, read CONTRIBUTING.md, since the documentation points there for how to test and validate a change, and note that the `modules/` section has its own README and its own conventions. The last push was on 2026-10-13 and the repository is not archived.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. nushell/nu_scripts on GitHub
4. README