nix-run — Universal CLI Tool Runner via Nix#

Automatically find and run any CLI tool through Nix with zero configuration. If the tool is installed locally, it runs directly with no overhead. If not, it auto-fetches from nixpkgs (100,000+ packages) on the fly.

CRITICAL RULES#

1. ALWAYS run CLI tools through scripts/nix-run.sh — even if you think the tool might already be installed. The script checks locally first (zero overhead) and auto-fetches via nix only if missing.
2. NEVER install packages via apt, brew, pip install, npm install -g, cargo install, or any other package manager. This system uses nix exclusively.
3. NEVER suggest the user install anything. Just run it through nix-run.
4. NEVER use nix shell or nix run directly. Always go through scripts/nix-run.sh which handles package detection automatically. For multi-package environments, use --shell.
5. On "command not found": Do NOT advise installation. Immediately retry through scripts/nix-run.sh.
6. When unsure which tool to use: Use --search to discover the right package, then run it.

Quick Start#

bash

# Run ANY command — auto-detects package, zero config
scripts/nix-run.sh <command> [args...]

# Multi-package environment — run command with multiple tools available
scripts/nix-run.sh --shell <pkg1,pkg2,...> -- <command> [args...]

# Don't know the command name? Search by keyword
scripts/nix-run.sh --search "<keyword>"

# Update nix-locate database to get latest package info
scripts/nix-run.sh --update

Workflows#

Workflow 1: Automatic Recovery from "command not found"#

When a bash command fails with "command not found", immediately retry through nix-run — do NOT suggest installing:

bash

# WRONG: "You need to install jq first: apt install jq"
# WRONG: brew install jq
# WRONG: nix shell nixpkgs#jq -c jq ...
# RIGHT:
scripts/nix-run.sh jq '.name' data.json

Workflow 2: Proactive Use — Always Prefer nix-run#

For any CLI tool, always go through nix-run first:

bash

scripts/nix-run.sh pandoc README.md -o README.pdf
scripts/nix-run.sh fd '\.rs$' src/
scripts/nix-run.sh rg 'TODO' .
scripts/nix-run.sh ffmpeg -i input.mp4 output.gif
scripts/nix-run.sh htop
scripts/nix-run.sh tree -L 2
scripts/nix-run.sh imagemagick convert input.png output.jpg
scripts/nix-run.sh shellcheck script.sh

Workflow 3: Discover Tools by Keyword#

When you need a CLI tool but don't know its name, search nixpkgs:

bash

scripts/nix-run.sh --search "json processor"
#   jq (1.8.1) - Lightweight and flexible command-line JSON processor
#   njq (...) - Command-line JSON processor using nix as query language

# Then run the discovered tool:
scripts/nix-run.sh jq '.name' data.json

Workflow 4: Handling Multiple Candidates#

When multiple packages provide the same command, nix-run lists candidates and exits. Re-run with --pkg:

bash

scripts/nix-run.sh --pkg ffmpeg-headless ffmpeg -version

Workflow 5: Multi-Package Environment with --shell#

When a task requires multiple tools available simultaneously (e.g., a Python script that calls node, or a build step needing several compilers):

bash

# Run a Python script that also needs node available
scripts/nix-run.sh --shell python3,nodejs -- python3 script.py

# Run multiple commands in a combined environment
scripts/nix-run.sh --shell python3,nodejs -- bash -c 'python3 --version && node --version'

# Data pipeline with jq and curl
scripts/nix-run.sh --shell jq,curl -- bash -c 'curl -s https://api.example.com | jq .data'

Options#

FlagDescription--pkg <name>Skip auto-detection, use specified nix package--shell <pkg1,...>Multi-package environment (comma-separated), use -- before command--search <keyword>Search nixpkgs by keyword (returns package name + description)--limit <N>Max search results (default: 20)--updateUpdate nix-locate database (nix-index) to latest nixpkgs

How It Works#

1. Command exists locally → execute directly (zero overhead)
2. --pkg specified → nix shell github:NixOS/nixpkgs/nixpkgs-unstable#<pkg> -c <cmd> <args>
3. --shell specified → nix shell nixpkgs#pkg1 nixpkgs#pkg2 ... -c <cmd> <args>
4. Otherwise → nix-locate to find the package providing /bin/<cmd>
5. Single candidate or exact match → run automatically
6. Multiple candidates → list them and exit (re-run with --pkg)

Note: All commands use nixpkgs-unstable flake reference to ensure latest package versions.

Edge Cases#

• Command not in nixpkgs: Exits with error. Use --search to find alternatives.
• nix-locate not installed: Exits with instructions to install nix-index.
• nix-locate database outdated: Run scripts/nix-run.sh --update to refresh.
• Software versions too old: The script uses nixpkgs-unstable by default, ensuring latest versions. If versions still seem stale, run --update to refresh the nix-locate index.
• First run may be slow: nix shell downloads on first use; subsequent runs use cache.