Getting started

Run without installing

With Nix (flakes enabled):

nix run github:nerima-lisp/nshell/v0.4.0

Install

nix profile install github:nerima-lisp/nshell/v0.4.0
nshell
man nshell   # the manual page is installed alongside the binary

Consumers inside the nerima-lisp org pin a release tag rather than following the default branch:

# flake.nix
inputs.nshell = {
  url = "github:nerima-lisp/nshell/v0.4.0";
  inputs.nixpkgs.follows = "nixpkgs";
};

The release workflow currently publishes an x86_64-linux tarball and SHA-256 checksum. Check the GitHub releases page before downloading: the v0.4.0 artifacts are not portable and may retain Nix store dependencies. For reproducible installation, use the pinned Nix commands above.

First commands

Start nshell and type as you would in any shell. The prompt shows the working directory, the git branch (with * when the tree is dirty), and a ❯ that turns red after a failing command; the last exit code and any command that took a second or more appear on the right. The distinguishing behaviour shows up while typing: commands colorize live (an unknown command turns red before you run it), existing paths are underlined, and a dimmed completion of the most recent matching history entry trails the cursor. Press → or Ctrl-F to accept it. A mistyped command gets a did you mean suggestion, FOO=bar cmd exports FOO for that one command, and theme list shows the color presets. The prompt layout, the colors, and the key bindings are all configurable; see Customization.

Set NSHELL_GREETING to replace the startup banner with your own line, or to the empty string to start silently. It is read after ~/.nshellrc runs, so set -x NSHELL_GREETING "" in that file works.

One-off command

nshell -c 'string upper hello'

Run a script

nshell examples/greet.nsh World

Script files support multiline blocks (functions, if/for/while/switch), comments, and a #! shebang; arguments after the script name are available as $argv. See examples/ for a runnable sample.

Command line

Usage: nshell [OPTIONS] [-c COMMAND [ARGS...]] [SCRIPT [ARGS...]]

Without arguments, nshell starts an interactive shell when stdin is a terminal
and reads batch input from stdin otherwise.
With -c/--command, nshell executes COMMAND once in batch mode; trailing ARGS
are available as $argv.
With SCRIPT, nshell runs the script file; trailing ARGS are available as $argv.

Options:
  -i, --interactive  Force the interactive line editor.
      --no-config    Do not load the interactive startup file.
      --config PATH  Load PATH instead of ~/.nshellrc.
      --no-history   Do not read or write interactive history.
  -h, --help          Show usage and exit.
  -V, --version       Show version and exit.

Build from source

nshell builds with SBCL and ASDF. The supported and tested path is Nix:

git clone https://github.com/nerima-lisp/nshell
cd nshell
nix build            # produces ./result/bin/nshell
nix flake check      # full hermetic gate on x86_64-linux CI
nix develop          # dev shell with SBCL + cl-weave

flake.nix declares x86_64-linux and aarch64-darwin. The full hermetic flake gate, the release-binary gate, and the non-sandboxed integration suite all run in CI on x86_64-linux only; aarch64-darwin is a local development target (nix build, nix develop), and some build checks can be unavailable there when a pinned upstream package has no Darwin build.

Inside nix develop, load the system into a REPL:

(asdf:load-system "nshell")
(nshell:main)