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. - NEVER install packages via
apt, brew, pip install, npm install -g, cargo install, or any other package manager. This system uses nix exclusively. - NEVER suggest the user install anything. Just run it through nix-run.
- 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. - On "command not found": Do NOT advise installation. Immediately retry through
scripts/nix-run.sh. - When unsure which tool to use: Use
--search to discover the right package, then run it.
Quick Start
CODEBLOCK0
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:
CODEBLOCK1
Workflow 2: Proactive Use — Always Prefer nix-run
For any CLI tool, always go through nix-run first:
CODEBLOCK2
Workflow 3: Discover Tools by Keyword
When you need a CLI tool but don't know its name, search nixpkgs:
CODEBLOCK3
Workflow 4: Handling Multiple Candidates
When multiple packages provide the same command, nix-run lists candidates and exits. Re-run with --pkg:
CODEBLOCK4
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):
CODEBLOCK5
Options
| Flag | Description |
|---|
| INLINECODE13 | Skip auto-detection, use specified nix package |
| INLINECODE14 |
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) |
|
--update | Update nix-locate database (nix-index) to latest nixpkgs |
How It Works
- 1. Command exists locally → execute directly (zero overhead)
- INLINECODE19 specified → INLINECODE20
- INLINECODE21 specified → INLINECODE22
- Otherwise →
nix-locate to find the package providing INLINECODE24 - Single candidate or exact match → run automatically
- 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.
nix-run — 通过 Nix 实现通用 CLI 工具运行器
自动查找并通过 Nix 运行任何 CLI 工具，零配置。如果工具已在本地安装，则直接运行，无额外开销。如果未安装，则自动从 nixpkgs（超过 100,000 个包）实时获取。
关键规则
- 1. 始终通过 scripts/nix-run.sh 运行 CLI 工具 — 即使你认为工具可能已安装。脚本会先检查本地（零开销），仅在缺失时通过 nix 自动获取。
- 绝不通过 apt、brew、pip install、npm install -g、cargo install 或任何其他包管理器安装包。本系统仅使用 nix。
- 绝不建议用户安装任何东西。 直接通过 nix-run 运行。
- 绝不直接使用 nix shell 或 nix run。 始终通过 scripts/nix-run.sh，它会自动处理包检测。对于多包环境，使用 --shell。
- 遇到命令未找到：不要建议安装。立即通过 scripts/nix-run.sh 重试。
- 不确定使用哪个工具时：使用 --search 发现正确的包，然后运行。
快速开始
bash
运行任何命令 — 自动检测包，零配置
scripts/nix-run.sh <命令> [参数...]
多包环境 — 在多个工具可用时运行命令
scripts/nix-run.sh --shell <包1,包2,...> -- <命令> [参数...]
不知道命令名称？按关键词搜索
scripts/nix-run.sh --search <关键词>
更新 nix-locate 数据库以获取最新包信息
scripts/nix-run.sh --update
工作流程
工作流程 1：从命令未找到自动恢复
当 bash 命令因命令未找到失败时，立即通过 nix-run 重试 — 不要建议安装：
bash
错误：你需要先安装 jq：apt install jq
错误：brew install jq
错误：nix shell nixpkgs#jq -c jq ...
正确：
scripts/nix-run.sh jq .name data.json
工作流程 2：主动使用 — 始终优先使用 nix-run
对于任何 CLI 工具，始终先通过 nix-run：
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
工作流程 3：按关键词发现工具
当你需要 CLI 工具但不知道名称时，搜索 nixpkgs：
bash
scripts/nix-run.sh --search json 处理器
jq (1.8.1) - 轻量级且灵活的 JSON 命令行处理器
njq (...) - 使用 nix 作为查询语言的 JSON 命令行处理器
然后运行发现的工具：
scripts/nix-run.sh jq .name data.json
工作流程 4：处理多个候选包
当多个包提供相同命令时，nix-run 列出候选包并退出。使用 --pkg 重新运行：
bash
scripts/nix-run.sh --pkg ffmpeg-headless ffmpeg -version
工作流程 5：使用 --shell 的多包环境
当任务需要同时使用多个工具时（例如，调用 node 的 Python 脚本，或需要多个编译器的构建步骤）：
bash
运行一个也需要 node 可用的 Python 脚本
scripts/nix-run.sh --shell python3,nodejs -- python3 script.py
在组合环境中运行多个命令
scripts/nix-run.sh --shell python3,nodejs -- bash -c python3 --version && node --version
使用 jq 和 curl 的数据管道
scripts/nix-run.sh --shell jq,curl -- bash -c curl -s https://api.example.com | jq .data
选项
| 标志 | 描述 |
|---|
| --pkg <名称> | 跳过自动检测，使用指定的 nix 包 |
| --shell <包1,...> |
多包环境（逗号分隔），在命令前使用 -- |
| --search <关键词> | 按关键词搜索 nixpkgs（返回包名称 + 描述） |
| --limit
| 最大搜索结果数（默认：20） |
| --update | 更新 nix-locate 数据库（nix-index）至最新 nixpkgs |
工作原理
- 1. 命令本地存在 → 直接执行（零开销）
- 指定 --pkg → nix shell github:NixOS/nixpkgs/nixpkgs-unstable#<包> -c <命令> <参数>
- 指定 --shell → nix shell nixpkgs#包1 nixpkgs#包2 ... -c <命令> <参数>
- 否则 → nix-locate 查找提供 /bin/<命令> 的包
- 单个候选包或精确匹配 → 自动运行
- 多个候选包 → 列出并退出（使用 --pkg 重新运行）
注意： 所有命令使用 nixpkgs-unstable flake 引用以确保最新包版本。
边界情况
- - 命令不在 nixpkgs 中：退出并报错。使用 --search 查找替代方案。
- nix-locate 未安装：退出并提示安装 nix-index。
- nix-locate 数据库过时：运行 scripts/nix-run.sh --update 刷新。
- 软件版本过旧：脚本默认使用 nixpkgs-unstable，确保最新版本。如果版本仍显陈旧，运行 --update 刷新 nix-locate 索引。
- 首次运行可能较慢：nix shell 首次使用会下载；后续运行使用缓存。
