CLI
nix-pins [OPTIONS] [COMMAND]
nix-pins update [PIN ...] [--filter REGEX]
nix-pins status [PIN ...] [--filter REGEX]
Commands
| Command | Behavior |
|---|---|
update | Check versions, compute source and dependency hashes for selected Pins, and write the Pins File |
status | Report existing results and failures for selected Pins without modifying them |
| No command | Same as status, selecting all Pins |
help, --help | Show help |
--version | Show the CLI version |
Global options
| Option | Default | Meaning |
|---|---|---|
--config PATH | ./pins-config.nix | Nix Pin declaration file |
--pins PATH | ./pins.json | Pins File to read and write |
--checker-jobs N | Half the CPU count, at least 1 | Concurrent version checks |
--download-jobs N | 2 | Concurrent downloads |
--hash-jobs N | Half the CPU count, at least 1 | Concurrent Nix evaluations and builds |
--github-api-base URL | https://api.github.com | GitHub API base URL |
--crates-api-base URL | https://crates.io | crates.io API base URL |
--pypi-api-base URL | https://pypi.org | PyPI API base URL |
--npm-registry-base URL | https://registry.npmjs.org | npm registry base URL |
--github-token TOKEN | Unset | GitHub API credential |
Global options can appear before or after the subcommand. Relative paths resolve from the current working directory. Each setting has a corresponding environment variable. --help shows variable names and default descriptions; see Runtime configuration for the full precedence rules.
nix-pins --config project/pins-config.nix update --pins project/pins.json
Selection
PIN is a configured name; you can provide several. --filter is a Rust regular expression applied to Pin names. Names and matches form a union. With neither, all Pins are selected. Unknown names, invalid regular expressions, and a filter-only selection with no matches are errors.
nix-pins update editor --filter '^language-'
Selection applies to Pins, not Sources or Packages. See Updating and selecting Pins for the full behavior.
Automation
Use exit codes to determine success instead of inferring it from TUI icons or output line counts. After a runtime failure, inspect status and failure records in the Pins File. Configuration files can execute external commands; run only trusted configurations.
There are currently no separate add, remove, init, or status --refresh commands. To add a Pin, edit the declaration and run update. After removing a Pin, run a full update.