Runtime configuration
Runtime settings have the following precedence, from lowest to highest: defaults → optional nix-pins.toml in the current directory → NIX_PINS_* environment variables → CLI arguments. Configuration fields, CLI arguments, and environment variables are declared once in Settings. Clap reads CLI arguments and environment variables; config-rs merges TOML with explicitly supplied values from ArgMatches; Serde fills in missing defaults. Pin declarations remain in pins-config.nix.
config = "./pins-config.nix"
file = "./pins.json"
download_jobs = 2
checker_jobs = 4
hash_jobs = 4
Fields
| Setting | Environment variable | CLI option | Default or description |
|---|---|---|---|
config | NIX_PINS_CONFIG | --config PATH | ./pins-config.nix |
file | NIX_PINS_FILE | --pins PATH | ./pins.json |
download_jobs | NIX_PINS_DOWNLOAD_JOBS | --download-jobs N | 2 |
checker_jobs | NIX_PINS_CHECKER_JOBS | --checker-jobs N | Half the available logical CPU count, rounded down, at least 1 |
hash_jobs | NIX_PINS_HASH_JOBS | --hash-jobs N | Same as above |
github_api_base | NIX_PINS_GITHUB_API_BASE | --github-api-base URL | Official GitHub API |
crates_api_base | NIX_PINS_CRATES_API_BASE | --crates-api-base URL | Official crates.io API |
pypi_api_base | NIX_PINS_PYPI_API_BASE | --pypi-api-base URL | Official PyPI API |
npm_registry_base | NIX_PINS_NPM_REGISTRY_BASE | --npm-registry-base URL | Official npm registry |
github_token | NIX_PINS_GITHUB_TOKEN | --github-token TOKEN | Optional GitHub token |
Concurrency values must be positive integers. Invalid configuration fails before Nix starts. Empty environment variables are treated as unset. GITHUB_TOKEN can also supply a token, with lower priority than the configuration file and NIX_PINS_GITHUB_TOKEN. Do not put tokens in configuration files committed to version control.
CLI options can appear before or after the subcommand. nix-pins update --help lists all settings, their environment variables, and default descriptions. Token environment variable values are not shown in help.
Concurrency queues
Once all version checks finish, Pins process their Sources and dependencies independently. Source downloads are limited by download_jobs; Nix evaluation and dependency builds share the hash_jobs limit. A Pin can enter the build queue as soon as its sources are ready. Multiple Sources in one Pin share these queues too.
Successful Pins immediately show ✔; failed Pins retain their previous results. A Pin updates only when every Source succeeds. Results are written together atomically at the end; cancellation writes nothing. Because downloads and builds can overlap, the overall phase is labeled Processing pins, with each node showing its specific step.
Increasing concurrency raises simultaneous network, Nix store, and CPU usage. If you encounter rate limits or local resource pressure, reduce the corresponding concurrency setting first.