{"id":51611153,"url":"https://github.com/takeokunn/nshell","last_synced_at":"2026-07-12T08:01:21.733Z","repository":{"id":366244924,"uuid":"1275551276","full_name":"takeokunn/nshell","owner":"takeokunn","description":"Modern, fish-inspired interactive shell written in Common Lisp","archived":false,"fork":false,"pushed_at":"2026-07-04T22:58:21.000Z","size":1331,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-04T23:04:34.236Z","etag":null,"topics":["command-line","common-lisp","fish","interactive-shell","nix","repl","sbcl","shell","terminal"],"latest_commit_sha":null,"homepage":"","language":"Common Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/takeokunn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-20T20:59:46.000Z","updated_at":"2026-07-04T22:58:24.000Z","dependencies_parsed_at":null,"dependency_job_id":"e93d6115-8197-4732-948f-4ab205d961ed","html_url":"https://github.com/takeokunn/nshell","commit_stats":null,"previous_names":["takeokunn/nshell"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/takeokunn/nshell","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/takeokunn%2Fnshell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/takeokunn%2Fnshell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/takeokunn%2Fnshell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/takeokunn%2Fnshell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/takeokunn","download_url":"https://codeload.github.com/takeokunn/nshell/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/takeokunn%2Fnshell/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35385772,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["command-line","common-lisp","fish","interactive-shell","nix","repl","sbcl","shell","terminal"],"created_at":"2026-07-12T08:01:20.957Z","updated_at":"2026-07-12T08:01:21.712Z","avatar_url":"https://github.com/takeokunn.png","language":"Common Lisp","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nshell\n\n**A modern, fish-inspired interactive shell written in Common Lisp.**\n\n[![CI](https://github.com/takeokunn/nshell/actions/workflows/ci.yml/badge.svg)](https://github.com/takeokunn/nshell/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)\n[![Built with Nix](https://img.shields.io/badge/built%20with-nix-5277C3.svg?logo=nixos\u0026logoColor=white)](https://nixos.org)\n\nnshell is an interactive shell that puts the *interactive* experience first:\nreal-time syntax highlighting, history-aware autosuggestions, fish-style\nabbreviations, and a fast, context-aware completion engine — all built on a\nclean, test-driven Common Lisp core (8,800+ checks) and a reproducible Nix\nbuild.\n\n\u003e **Status: early development (0.4.x).** The interactive editor and core\n\u003e pipeline execution are solid and heavily tested. The shell *language* is a\n\u003e growing subset of POSIX/fish semantics — see [Roadmap](#roadmap) for what is\n\u003e and isn't supported yet. nshell is usable as a daily interactive shell for\n\u003e common workflows; it is not a script-compatible `/bin/sh` replacement.\n\n---\n\n## Highlights\n\n- **Syntax highlighting** as you type — commands, strings, operators, and paths\n  are colorized live.\n- **Autosuggestions** from your history, fish-style, accepted with `→` / `Ctrl-F`.\n- **Abbreviations** (`abbr`) that expand inline as you type — keep your muscle\n  memory, type less.\n- **Context-aware completion** — a knowledge base of commands/flags plus\n  filesystem completion, with common-prefix `Tab` extension and a candidate menu.\n- **Rich line editing** — Emacs keybindings, kill-ring \u0026 yank, multi-level\n  undo/redo, multiline editing, and incremental history search (`Ctrl-R`).\n  Optional **vi key bindings** (`NSHELL_VI_MODE=1`): normal-mode motions,\n  counts, operators (`dd`, `cw`, …), visual selection, and insert/append.\n- **Configurable prompt** — hostname, working directory, git branch/dirty\n  status, command duration, and exit code, with theming.\n- **Job control** — background jobs (`\u0026`), `jobs`, `fg`, `bg`, `disown`.\n- **Pipelines \u0026 redirection** — `|`, `\u003e`, `\u003e\u003e`, `\u003c`, `\u003c\u003c`, `\u003c\u003c\u003c`, logical\n  `\u0026\u0026` / `||`, and command sequencing.\n- **Control flow \u0026 functions** — `if`, `for`, `while`, `switch`, `begin`/`end`,\n  and user-defined `function`s.\n- **Reproducible build** — a single statically-dumped SBCL image via Nix;\n  `nix run` and you're in.\n\n## Quick start\n\nWith [Nix](https://nixos.org/download) (flakes enabled), run nshell without\ninstalling anything:\n\n```sh\nnix run github:takeokunn/nshell\n```\n\nOr build a binary into your profile:\n\n```sh\nnix profile install github:takeokunn/nshell\nnshell\nman nshell   # the manual page is installed alongside the binary\n```\n\n### One-off command\n\n```sh\nnshell -c 'echo hello | string upper'\n```\n\n### Run a script\n\n```sh\nnshell examples/greet.nsh World\n```\n\nScript files support multiline blocks (functions, `if`/`for`/`while`/`switch`),\ncomments, and a `#!` shebang; arguments after the script name are available as\n`$argv`. See [`examples/`](./examples) for a runnable sample.\n\n### CLI\n\n```\nUsage: nshell [--help] [--version] [-c COMMAND [ARGS...]] [SCRIPT [ARGS...]]\n\nWithout arguments, nshell starts an interactive shell when stdin is a terminal\nand reads batch input from stdin otherwise.\nWith -c/--command, nshell executes COMMAND once in batch mode; trailing ARGS are available as $argv.\nWith SCRIPT, nshell runs the script file; trailing ARGS are available as $argv.\n```\n\n## Building from source\n\nnshell builds with [SBCL](http://www.sbcl.org/) and ASDF. The supported and\ntested path is Nix:\n\n```sh\ngit clone https://github.com/takeokunn/nshell\ncd nshell\nnix build            # produces ./result/bin/nshell\nnix flake check --print-build-logs\nnix develop          # dev shell with SBCL + FiveAM\n```\n\nInside `nix develop`, you can load the system into a REPL:\n\n```lisp\n(asdf:load-system :nshell)\n(nshell:main)\n```\n\n## Built-in commands\n\n`alias`, `abbr`, `bg`, `cd`, `complete`, `contains`, `count`, `disown`, `echo`,\n`exec`, `exit`, `export`, `false`, `fg`, `function`, `help`, `history`, `jobs`,\n`ls`, `not`, `pwd`, `read`, `seq`, `set`, `source`, `string`, `test`, `true`,\n`type`, `which`.\n\nRun `help` inside nshell for details.\n\n## Architecture\n\nnshell follows a domain-driven, layered design. Each layer depends only on the\nlayers beneath it:\n\n```\nsrc/\n├── domain/          Pure shell logic: parsing, expansion, completion,\n│                    history, prompting, job-control — no I/O.\n├── application/     Use cases: builtins, pipeline execution, job management.\n├── infrastructure/  ACLs over the OS: syscalls, PTY, signals, terminal I/O,\n│                    persistence. SBCL-specific code is isolated here.\n└── presentation/    The REPL, line editor (input-state reducer), rendering,\n                     highlighting, autosuggestions, completion UI.\n```\n\nThe REPL is structured as a **continuation-passing / trampoline loop**: each\nkeystroke runs a pure reducer over an immutable `input-state`, and rendering is\nderived from that state. This keeps the interactive core deterministic and\nunit-testable without a terminal.\n\n## Testing\n\nThe suite uses [FiveAM](https://github.com/lispci/fiveam) and is exposed through\nNix checks.\n\nRun the same hermetic Linux/macOS gate used by CI:\n\n```sh\nnix flake check --print-build-logs\n```\n\nRun only the current platform's test derivation:\n\n```sh\nnix build .#checks.$(nix eval --impure --raw --expr builtins.currentSystem).test\n```\n\nRun the full non-sandboxed integration suite when changing PTY, subprocess,\nterminal, or job-control behavior. This covers the real-PTY interactive smoke,\nCtrl-C recovery, and job-control lifecycle checks that are intentionally skipped\ninside hermetic Nix builds:\n\n```sh\nnix develop -c sbcl --non-interactive \\\n  --eval '(require :asdf)' \\\n  --eval '(push (truename \"./\") asdf:*central-registry*)' \\\n  --eval '(asdf:test-system :nshell/test)'\n```\n\nGenerate an HTML coverage report for the same suite:\n\n```sh\nnix develop -c sbcl --script scripts/coverage.lisp\n```\n\nThe report is written to `coverage/cover-index.html` by default. Set\n`NSHELL_COVERAGE_DIR` to redirect the output.\n\nUnit, integration, property-based, and end-to-end tests live under `tests/`.\nNew shell-language, expansion, completion, job-control, and input-state changes\nshould include focused regression tests plus the relevant property or PTY\ncoverage when behavior crosses process, terminal, or parser boundaries. See\n`CONTRIBUTING.md` for test-selection expectations.\n\n## Roadmap\n\nnshell is converging on world-class interactive-shell parity. Near-term focus:\n\n- **Shell language depth** — richer list variables and explicit semantics\n  around compound expansions.\n  (Quoting, parameter expansion with defaults, required checks, substring\n  slicing, and patterns, arithmetic `$((...))`, brace expansion, command\n  substitution `$(...)`/`(...)`, fd redirections `2\u003e`/`2\u003e\u00261`/`\u0026\u003e`, here-docs\n  `\u003c\u003c`, here-strings `\u003c\u003c\u003c`, and function arguments via `$argv`/`$argv[N]` are\n  done.)\n- **Job control hardening** — robust foreground process-group handling so\n  `Ctrl-C` / `Ctrl-Z` reliably interrupt and suspend pipelines.\n- **Completion intelligence** — broader command metadata and higher-fidelity\n  flag/value completion.\n- **Distribution** — nixpkgs, Homebrew, and prebuilt release binaries.\n\nSee [CHANGELOG.md](./CHANGELOG.md) for released changes.\n\nFor release qualification, see [PUBLIC_READINESS.md](./PUBLIC_READINESS.md).\n\n## Contributing\n\nContributions are welcome. Please run `nix flake check --print-build-logs`\nbefore opening a pull request; CI runs that hermetic gate on Linux and macOS\nand also runs the full non-sandboxed integration suite on Linux. See\n`CONTRIBUTING.md` for style, test, semantics, and issue-reporting\nexpectations.\n\n## Security\n\nPlease report vulnerabilities privately instead of opening a public issue. See\n`SECURITY.md` for the supported scope, report contents, and disclosure process.\n\n## License\n\n[MIT](./LICENSE) © the nshell authors.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftakeokunn%2Fnshell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftakeokunn%2Fnshell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftakeokunn%2Fnshell/lists"}