nxr

Ergonomic command plane for standard Nix flake outputs.

nxr test is the pleasant form of nix run .#test. Flake apps stay the canonical leaf operations; nix run remains the escape hatch. nxr adds discovery, task DAGs, diagnostics, shell integration, and an operator TUI— without becoming a second toolchain or a parallel Nix.

Consumer guides live on the GitHub Wiki. This README is the landing page; docs/ is for contributors, ADRs, and the design contract.

Install

nix profile install github:willmortimer/nxr#nxr
# or: nix shell github:willmortimer/nxr#nxr

Pre-built release tarballs: docs/RELEASE.md. Step-by-step: Wiki · Install.

Flake-parts (session completion + PATH; optional schemas):

imports = [ inputs.nxr.flakeModules.default ];

perSystem.nxr = {
  shellIntegration.enable = true;
  tasks.ci = { app = "ci"; };
};

Details: docs/DEV_ENV_INTEGRATION.md, docs/TASKS.md.

Quick start

nxr list                  # apps (+ tasks when present)
nxr test                  # ≈ nix run .#test
nxr task ci -j 8          # inspectable DAG; same graph locally and in CI
nxr ui                    # Apps / Tasks / Scripts browser (TTY)
nxr task ci --output tui  # Ratatui DAG watch
nxr attach                # reopen the last attachable TUI run

Inline flake + app (like nix run):

nxr ./path/to/flake#hello
nxr --flake ./path/to/flake hello

Operator TUI

Command	What it does
nxr ui	Lazygit-style browser; Enter runs apps / task --output tui / scripts
nxr … --output tui	One-screen DAG watch (node table + log tail); non-TTY falls back to live
nxr attach [RUN]	Reopen a recorded watch (omit RUN → most recent; fail closed if none)

More: Wiki · Interactive TUI, ADR-0173. Demo GIFs: tui · ui · wizard.

Decision-style flows stay wizard flake apps → nxr task … (no schema when). See fixtures/deploy-wizard and Wiki · Tasks and DAGs.

Everyday commands

Command	What it does
nxr / nxr list	List apps (and tasks)
nxr <app> [args…]	Run a flake app (apps only — not tasks)
nxr task <name>… [-j N]	Run task roots (union DAG; shared deps once)
nxr script <path|name>	Local workspace script (.nxr/scripts/ or path)
nxr graph <name>	Print the plan (--format text|mermaid|dot)
nxr watch <name>	Kill + rerun on flake-root changes
nxr plan / explain	Exact Nix argv, cwd, cache key, capabilities
nxr doctor --all	Environment + workspace findings
nxr affected …	Conservative path→app/task analysis for CI
nxr ci plan [--json]	Provider-neutral CI execution plan
nxr migrate justfile|mise	Suggest perSystem.nxr.* (never runs recipes)

Useful globals: --flake, --cwd / --root, --shell / --shell-mode, --output live|grouped|failures|summary|raw|tui, --events jsonl.

Full CLI index: docs/CLI_REFERENCE.md.

Tasks and CI ≡ local

nxr task ci
nxr task lint unit integration -j 8
nxr graph release --format mermaid
nxr ci plan --json

Guide: Wiki · Tasks and DAGs, docs/TASKS.md. CI/release walkthrough: Wiki · CI and Release.

Coming from mise / just

nxr migrate mise
nxr migrate justfile

Wiki · Migrations · docs/MIGRATE_FROM_MISE_JUST.md.

Documentation map

Audience	Where
Users	GitHub Wiki (Install, Tasks, TUI, CI, Migrations)
Contributors / agents	docs/INDEX.md, CONTRACT_SUMMARY, ADRs
This repo	docs/CONTRIBUTING.md, docs/RELEASE.md

Wiki source markdown (publish with ./scripts/publish-wiki.sh): wiki/.

Developing this repository

nxr task ci          # host: fmt-check → lint → test → deny → cli-ref
nxr task ci-linux    # Linux OS parity (OrbStack/Docker; native on Linux)
nxr task release     # dependsOn [ci, ci-linux], then tag helper

License

MIT — see LICENSE.

Status

3.7.1 (tagged) — portable .nxr/workflows.toml graphs (nxr workflow), native tasks without Nix, and remote WinExec/WinBuild submission. nxr task still uses the flake task document. Operator archives stay Darwin and Linux.

History: CHANGELOG.md · roadmap: docs/ROADMAP.md.