### Install Nix Packages and Dependencies

Source: https://github.com/vic/nix-versions/blob/main/docs/installing-packages-on-profiles.md

Installs specified Nix packages and their dependencies into a target directory. It utilizes `nix profile install` with a list of installables generated by `nix-versions`. The example shows installing `cargo` and `glibc` with specific output selectors.

```shell
> mkdir tmp
> nix profile install --profile $PWD/tmp/my-tools $(nix-versions -i cargo@latest glibc^static,dev@latest)
> export PATH=$PWD/tmp/my-tools/bin:$PATH
> which cargo
/home/foo/tmp/my-tools/bin/cargo
```

--------------------------------

### Direnv Integration - Fast Track Endpoint

Source: https://context7.com/vic/nix-versions/llms.txt

Quick environment setup using the web endpoint without local nix-versions installation.

```APIDOC
## Direnv Integration - Fast Track Endpoint

Quick environment setup using the web endpoint without local nix-versions installation.

### Step 1: Get hash for the script with your tools
```bash
direnv fetchurl "https://nix-versions.oeiuwq.com/use_nix_tools.sh/go/ruby"
```

### Step 2: Create .envrc with the fetched script
```bash
cat > .envrc << 'EOF'
source_url "https://nix-versions.oeiuwq.com/use_nix_tools.sh/go/ruby" "sha256-HASH_FROM_ABOVE"
EOF
```

### Step 3: Allow and reload
```bash
direnv allow
direnv reload
```
```

--------------------------------

### Install and Run Nix Versions CLI

Source: https://context7.com/vic/nix-versions/llms.txt

Demonstrates how to run the Nix Versions CLI tool directly without installation using 'nix run' or how to install it permanently to your system's profile for persistent access.

```bash
# Run directly without installation
nix run github:vic/nix-versions -- --help

# Install to your profile for permanent access
nix profile install github:vic/nix-versions
nix-versions --help
```

--------------------------------

### Search Nix Packages by Attribute Path

Source: https://github.com/vic/nix-versions/blob/main/docs/getting-started/finding-packages.md

Demonstrates searching for Nix packages using their attribute paths. This is a fundamental step for installing packages. Examples include simple paths like 'emacs' and nested paths like 'python312Packages.pip'.

```shell
# Example of simple attribute paths
emacs
ruby
go
cargo
zig
nodejs

# Example of nested attribute path
python312Packages.pip
```

--------------------------------

### List Local System Versions of a Package

Source: https://github.com/vic/nix-versions/blob/main/docs/getting-started/listing-versions.md

This command lists the versions of a package available on your system's nixpkgs tree using the `system:` backend prefix. This allows you to query local installations.

```shell
<!-- @include: ./emacs-local.ansi.bash -->
```

--------------------------------

### Direnv Integration via Fast Track Web Endpoint

Source: https://context7.com/vic/nix-versions/llms.txt

Quickly set up development environments with direnv using a web endpoint without needing a local nix-versions installation. Fetch a script hash and use it in your .envrc.

```bash
# Get hash for the script with your tools
direnv fetchurl "https://nix-versions.oeiuwq.com/use_nix_tools.sh/go/ruby"

# Create .envrc with the fetched script
cat > .envrc << 'EOF'
source_url "https://nix-versions.oeiuwq.com/use_nix_tools.sh/go/ruby" "sha256-HASH_FROM_ABOVE"
EOF

# Allow and reload
direnv allow
direnv reload
```

--------------------------------

### Read and Combine Nix Package Specifications

Source: https://context7.com/vic/nix-versions/llms.txt

Read package specifications from a .nix_tools file and combine them with installable output. This is useful for managing and referencing specific package versions.

```bash
# Read specs from file
nix-versions --read .nix_tools

# Combine with installable output
nix-versions -ir .nix_tools
```

--------------------------------

### Enter nix-shell with default.zip

Source: https://github.com/vic/nix-versions/blob/main/docs/non-flake-environments.md

Shows how to enter a `nix-shell` environment using a `default.zip` archive for a specific tool (e.g., Ruby) at its latest version. This is an experimental feature for non-flake setups.

```shell
nix-shell https://nix-versions.oeiuwq.com/default.zip/ruby@latest -A devShell
```

--------------------------------

### Generate Nix Installables - Shell

Source: https://github.com/vic/nix-versions/blob/main/docs/tools-version-manager.md

Generates a list of Nix Installables (flake-output-attributes) for specified packages and versions. This output can be directly used by `nix shell` to create an environment with the desired tools.

```shell
nix-versions --installable go@1.24.x ruby@latest
```

--------------------------------

### Control Nix Versions CLI Output Format

Source: https://context7.com/vic/nix-versions/llms.txt

Explains various command-line options for Nix Versions CLI to control output, including showing all matching versions, the single latest version, JSON output, Nix installables, and disabling colorization.

```bash
# Show all versions with constraint highlighting (matching versions colored)
nix-versions 'emacs@~27 || ~29' --all

# Show only the latest version matching the constraint
nix-versions 'emacs@~27 || ~29' --one
nix-versions 'go@1.24.x' -1

# Output as JSON array
nix-versions go@latest --json

# Output as Nix installables (for use with nix shell)
nix-versions --installable go@1.24.x ruby@latest
# Output:
# nixpkgs/de0fe301211c267807afd11b12613f5511ff7433#go_1_24
# nixpkgs/0d534853a55b5d02a4ababa1d71921ce8f0aee4c#ruby_3_4

# Disable colored output
nix-versions emacs --all --color=false
```

--------------------------------

### List Package Versions with Regexp Constraints

Source: https://github.com/vic/nix-versions/blob/main/docs/getting-started/listing-versions.md

This command allows filtering package versions using regular expressions when SemVer conventions are not followed. The constraint must end with `$` to indicate regexp matching, and it's recommended to start with `^`.

```shell
<!-- @include: ./leanify-regexp-all.ansi.bash -->
```

--------------------------------

### Direnv Integration with use_nix_tools

Source: https://context7.com/vic/nix-versions/llms.txt

Automatically load development environments using direnv and the `use_nix_tools` function. This involves installing the function globally and creating .nix_tools and .envrc files in your project.

```bash
# Install the use_nix_tools function globally
mkdir -p ~/.config/direnv/lib
curl "https://nix-versions.oeiuwq.com/use_nix_tools.sh" -o ~/.config/direnv/lib/use_nix_tools.sh

# Create .nix_tools file in your project
cat > .nix_tools << 'EOF'
ruby@~3.4
nodejs@20.x
go@~1.24
EOF

# Create .envrc to use the tools
cat > .envrc << 'EOF'
use nix_tools
EOF

# Allow direnv to load the environment
direnv allow

# Environment automatically loads when entering directory
```

--------------------------------

### Generate Direnv Shell with Nix Versions

Source: https://github.com/vic/nix-versions/blob/main/docs/README.md

This command illustrates how to integrate `nix-versions` with `direnv` for on-the-fly environment setup. It fetches a shell script that provides specific tool versions (e.g., Ruby and Cowsay) without requiring `nix-versions` to be pre-installed, relying only on `nix` and `direnv`.

```shell
direnv fetchurl "https://nix-versions.oeiuwq.com/use_nix_tools.sh/ruby/cowsay"
```

--------------------------------

### Get Direnv Integration Script (REST API)

Source: https://context7.com/vic/nix-versions/llms.txt

Provides a base shell script designed for direnv integration, simplifying the setup of Nix development environments. It can optionally include pre-resolved package specifications.

```shell
curl https://nix-versions.oeiuwq.com/use_nix_tools.sh
```

```shell
curl https://nix-versions.oeiuwq.com/use_nix_tools.sh/go/ruby/nodejs
```

--------------------------------

### Get Default Nix Archive (REST API)

Source: https://context7.com/vic/nix-versions/llms.txt

Returns a ZIP archive containing the default.nix file for specified package versions. This is useful for scenarios where a packaged Nix build definition is required.

```shell
curl https://nix-versions.oeiuwq.com/default.zip/nodejs@20.x
```

--------------------------------

### Read Package Specs from File - Shell

Source: https://github.com/vic/nix-versions/blob/main/docs/tools-version-manager.md

Reads package specifications from a plain-text file (conventionally named .nix_tools) and generates Nix Installables. This allows for managing tool requirements in a file, supporting version constraints and referencing existing version files.

```shell
nix-versions --read .nix_tools --installable
```

--------------------------------

### Get Default Nix Content (REST API)

Source: https://context7.com/vic/nix-versions/llms.txt

Retrieves the content of a default.nix file for specified package versions. This endpoint is experimental and intended for integration with tools that require direct access to Nix build definitions.

```shell
curl https://nix-versions.oeiuwq.com/default.nix/go@1.24.x/ruby@~3.4
```

--------------------------------

### Visualize All Matching Package Versions with SemVer Constraints

Source: https://github.com/vic/nix-versions/blob/main/docs/getting-started/listing-versions.md

This command uses the `--all` flag to visualize all matching package versions against all available versions, using SemVer constraints. It helps in understanding the distribution of versions relative to the constraints.

```shell
nix-versions 'emacs@~27 || ~29' --all
```

--------------------------------

### Read Package Specs from File with Nix Versions

Source: https://context7.com/vic/nix-versions/llms.txt

Shows how to create a configuration file (e.g., '.nix_tools') to specify packages and their version constraints, which can then be read by the Nix Versions CLI, supporting comments and reading constraints from other files.

```bash
# Create a .nix_tools file
cat > .nix_tools << 'EOF'
# Comments are supported
ruby@latest
go       >= 1.24  <1.26
nodejs   .node-version    # Read constraint from existing file
EOF
```

--------------------------------

### List Ruby Implementations (Bash)

Source: https://github.com/vic/nix-versions/blob/main/docs/getting-started/finding-packages.md

Demonstrates how to list different Ruby implementations available in Nix. This helps in managing and selecting specific Ruby versions for development.

```shell
#!/bin/bash
nix-shell -p nix-shell --run "nix-env -qaP --description 'ruby'"

```

--------------------------------

### Specify Nix Versions Backend Services

Source: https://context7.com/vic/nix-versions/llms.txt

Demonstrates how to explicitly select backend services for version lookups on a per-package basis using prefixes like 'nixhub:', 'lazamar:', 'history:', and 'system:'.

```bash
# Use NixHub backend (default)
nix-versions nixhub:emacs

# Use Lazamar backend with specific channel
nix-versions 'lazamar:nixpkgs-unstable:emacs'
nix-versions 'lazamar:nixos-24.05:ruby'
nix-versions 'lazamar:nixos-21.05:go'

# Use history.nix-packages.com backend
nix-versions history:emacs

# Query your local nixpkgs tree
nix-versions system:emacs

# Compare versions across backends in single command
nix-versions nixhub:emacs lazamar:nixpkgs-unstable:emacs history:emacs system:emacs
```

--------------------------------

### Set Default Backend for Nix Versions CLI

Source: https://context7.com/vic/nix-versions/llms.txt

Shows how to configure a default backend service for all queries made with the Nix Versions CLI, using flags like '--nixhub', '--history', or '--lazamar' with an optional channel.

```bash
# Use NixHub as default (this is the default)
nix-versions --nixhub emacs ruby go

# Use history.nix-packages.com as default
nix-versions --history emacs ruby go

# Use Lazamar with specific channel as default
nix-versions --channel nixos-24.05 emacs ruby go
nix-versions --lazamar emacs ruby  # Uses nixpkgs-unstable channel
```

--------------------------------

### Find Packages by Program Name with Nix Versions

Source: https://context7.com/vic/nix-versions/llms.txt

Demonstrates how to use Nix Versions CLI to search for packages that provide a specific program binary, using the 'bin/' prefix followed by the program name or a wildcard pattern.

```bash
# Find packages providing emacsclient binary
nix-versions 'bin/emacsclient' --one

# Find packages providing ruby interpreter
nix-versions 'bin/ruby'

# Find packages providing gleam
nix-versions 'bin/gleam'

# Wildcard in program name
nix-versions 'bin/cargo*'
```

--------------------------------

### List Package Versions with Nix Versions CLI

Source: https://context7.com/vic/nix-versions/llms.txt

Shows basic usage of the Nix Versions CLI to list all available versions for a given package from nixpkgs repositories. It illustrates equivalent syntaxes for specifying package versions.

```bash
# List all emacs versions (all these are equivalent)
nix-versions emacs
nix-versions emacs@*
nix-versions emacs@

# Output shows versions with nixpkgs revisions:
# nixpkgs/de0fe301211c...  emacs  30.1
# nixpkgs/a1b2c3d4e5f6...  emacs  29.4
# nixpkgs/f6e5d4c3b2a1...  emacs  29.3
# ...
```

--------------------------------

### Display CLI Help (HTML)

Source: https://github.com/vic/nix-versions/blob/main/docs/getting-started/cli-help.md

This snippet renders the CLI help message using HTML, suitable for web-based interfaces or documentation. It assumes an environment capable of rendering HTML content. The output is derived from the same source as the ANSI version.

```html
<pre class="ansi-to-html">
<!-- @include: ./cli-help.ansi.html -->
</pre>
```

--------------------------------

### Fetch Nix Tools Script URL - Bash

Source: https://github.com/vic/nix-versions/blob/main/docs/tools-version-manager.md

Fetches the URL for the use_nix_tools.sh script, which can be sourced in a .envrc file to set up a development environment. This script resolves nix-installables and can be used independently of the nix-versions tool.

```bash
# Place this on your .envrc
source_url "https://nix-versions.oeiuwq.com/use_nix_tools.sh/go/ruby" HASH

# Where HASH can be obtained with:
direnv fetchurl "https://nix-versions.oeiuwq.com/use_nix_tools.sh/go/ruby"
```

--------------------------------

### Get Nixpkgs SRI Hash (REST API)

Source: https://context7.com/vic/nix-versions/llms.txt

Fetches the Source Replacement Integrity (SRI) hash for a given nixpkgs revision. This is crucial for ensuring the integrity and reproducibility of Nix package builds by verifying the source code.

```shell
curl https://nix-versions.oeiuwq.com/nixpkgs-sri/<revision>
```

--------------------------------

### Run Nix Versions CLI to Explore Tool Versions

Source: https://github.com/vic/nix-versions/blob/main/docs/README.md

This command demonstrates how to use the `nix-versions` CLI to find and select specific versions of a tool, such as Emacs. It showcases the flexibility in version specifiers like '~27' or '~29' and the '--all' flag to list all available versions.

```shell
nix run github:vic/nix-versions -- 'emacs@~27 || ~29' --all
```

--------------------------------

### Display CLI Help (Bash)

Source: https://github.com/vic/nix-versions/blob/main/docs/getting-started/cli-help.md

This snippet displays the help message for the CLI tool in a bash shell environment. It shows available commands, options, and their descriptions. No external dependencies are required beyond a standard bash shell.

```bash
#@include: ./cli-help.ansi.bash
```

--------------------------------

### Enter Nix Shell Environment - Shell

Source: https://github.com/vic/nix-versions/blob/main/docs/tools-version-manager.md

Enters a Nix development shell environment by combining `nix shell` with the output of `nix-versions`. This command reads package specifications from the .nix_tools file and creates a shell with the pinned versions of the specified tools.

```shell
nix shell $(nix-versions -ir .nix_tools)
```

--------------------------------

### Set Default Versions Backend (Bash)

Source: https://github.com/vic/nix-versions/blob/main/docs/getting-started/finding-packages.md

Configures the default backend for fetching version information. By default, NixHub is used, but it can be overridden with options like '--nixhub', '--history', or '--channel' for Lazamar.

```shell
#!/bin/bash
nix-shell -p nix-shell --run "nix-env -qaP --description 'emacs' --channel 'nixos-23.05'"

```

--------------------------------

### Compare Package Versions Across Backends

Source: https://github.com/vic/nix-versions/blob/main/docs/getting-started/finding-packages.md

Shows how to use nix-versions to compare the availability of a package's versions across different search backends (NixHub, Lazamar, history, system). This allows for a comprehensive view of package versioning.

```shell
# Example: Compare 'emacs' versions across multiple backends
nix run nixpkgs#nix-versions -- emacs --nixhub --lazamar nixpkgs-unstable --history --system
```

--------------------------------

### Filter Package Versions with Semantic Versioning Constraints

Source: https://context7.com/vic/nix-versions/llms.txt

Demonstrates how to use Nix Versions CLI to filter package versions based on semantic versioning constraints, including ranges, caret, and hyphen notations for precise version selection.

```bash
# Get emacs versions from 27.x or 29.x series only
nix-versions 'emacs@~27 || ~29'

# Get go version 1.24.x (patch-level updates allowed)
nix-versions 'go@~1.24'
nix-versions 'go@1.24.x'

# Get nodejs between versions 18 and 20 (exclusive)
nix-versions 'nodejs@>=18 <20'

# Hyphen range (1.0.0 to 2.0.0 inclusive)
nix-versions 'ruby@1.0 - 2.0'

# Caret range (minor updates allowed)
nix-versions 'rust@^1.70'
```

--------------------------------

### Fetch default.nix using curl

Source: https://github.com/vic/nix-versions/blob/main/docs/non-flake-environments.md

Demonstrates how to fetch a `default.nix` file for a specific tool (e.g., Ruby) at its latest version using `curl`. This is intended for non-flake environments.

```shell
curl https://nix-versions.oeiuwq.com/default.nix/ruby@latest -o default.nix
```

--------------------------------

### Show Only Latest Matching Package Version with SemVer Constraints

Source: https://github.com/vic/nix-versions/blob/main/docs/getting-started/listing-versions.md

This command uses the `--one` flag to display only the latest version that satisfies the specified SemVer constraint. This is useful when you only need the most recent compatible version.

```shell
<!-- @include: ./emacs-27-29-one.ansi.bash -->
```

--------------------------------

### List All Versions of a Package

Source: https://github.com/vic/nix-versions/blob/main/docs/getting-started/listing-versions.md

This command lists all available versions for a given package specifier. The `emacs@*` specifier requests any version of emacs. This is equivalent to just `emacs` or `emacs@` with an empty constraint.

```shell
<!-- @include: ./emacs-all.ansi.bash -->
```

--------------------------------

### Experimental Non-Flakes Endpoints

Source: https://github.com/vic/nix-versions/blob/main/docs/non-flake-environments.md

These endpoints, `default.nix` and `default.zip`, are experimental and intended for use in non-flake environments. They allow fetching package definitions and shell environments respectively.

```APIDOC
## Experimental Non-Flakes Endpoints

### Description
Provides experimental endpoints (`default.nix` and `default.zip`) for users not utilizing Nix flakes. These endpoints allow fetching Nix expressions and shell environments for specified packages and versions.

### Method
GET

### Endpoint
`https://nix-versions.oeiuwq.com/default.nix/<package>@<version>`
`https://nix-versions.oeiuwq.com/default.zip/<package>@<version>`

### Parameters
#### Path Parameters
- **package** (string) - Required - The name of the package to fetch.
- **version** (string) - Required - The desired version of the package (e.g., `latest`).

### Request Example
```shell
curl https://nix-versions.oeiuwq.com/default.nix/ruby@latest -o default.nix

nix-shell https://nix-versions.oeiuwq.com/default.zip/ruby@latest -A devShell
```

### Response
#### Success Response (200)
- **default.nix**: A Nix expression file for the requested package and version.
- **default.zip**: A zip archive containing the development shell environment for the requested package and version.

#### Response Example
(Content will be a Nix file or a zip archive, not a JSON object)

### Notes
These endpoints are marked as *experimental* because generating `default.nix` requires the server to download Nixpkgs and generate SRI checksums, which can consume server resources. As more users adopt flakes, non-flake features are considered experimental.
```

--------------------------------

### Non-Flake Environments - default.nix

Source: https://context7.com/vic/nix-versions/llms.txt

Experimental endpoints for generating non-flake Nix environments using `default.nix`.

```APIDOC
## Non-Flake Environments - default.nix

Experimental endpoints for non-flake Nix environments.

### Example 1: Download generated default.nix
```bash
curl https://nix-versions.oeiuwq.com/default.nix/ruby@latest -o default.nix
```

### Example 2: Use with nix-shell
```bash
nix-shell https://nix-versions.oeiuwq.com/default.zip/ruby@latest -A devShell
```

### The `default.nix` provides:
- `tools`: attribute set with package metadata
- `nixpkgs`: fetched nixpkgs for each tool
- `packages`: the actual packages
- `pkgsEnv`: `buildEnv` with all packages
- `devShell`: `mkShell` with packages
```

--------------------------------

### Direnv Integration - use_nix_tools

Source: https://context7.com/vic/nix-versions/llms.txt

Automatic environment loading with direnv when entering project directories using the `use_nix_tools` function.

```APIDOC
## Direnv Integration - use_nix_tools

Automatic environment loading with direnv when entering project directories.

### Step 1: Install the use_nix_tools function globally
```bash
mkdir -p ~/.config/direnv/lib
curl "https://nix-versions.oeiuwq.com/use_nix_tools.sh" -o ~/.config/direnv/lib/use_nix_tools.sh
```

### Step 2: Create .nix_tools file in your project
```bash
cat > .nix_tools << 'EOF'
ruby@~3.4
nodejs@20.x
go@~1.24
EOF
```

### Step 3: Create .envrc to use the tools
```bash
cat > .envrc << 'EOF'
use nix_tools
EOF
```

### Step 4: Allow direnv to load the environment
```bash
direnv allow
```

### Result
The environment automatically loads when entering the directory.
```

--------------------------------

### Filter Package Versions with Regex Constraints

Source: https://context7.com/vic/nix-versions/llms.txt

Illustrates using regular expressions with Nix Versions CLI to match package versions that do not strictly follow semantic versioning, particularly useful for date-based or custom versioning schemes.

```bash
# Match versions using regex (must end with $)
nix-versions 'leanify@^0\.8$'

# Match date-based versions
nix-versions 'package@^2024-.*$'
```

--------------------------------

### Use flake.zip Endpoint as Flake Input

Source: https://context7.com/vic/nix-versions/llms.txt

Utilize the `flake.zip` endpoint as a direct input for your own Nix flakes. This allows you to easily include version-pinned packages from nix-versions into your project's flake.

```bash
# Download as archive
curl https://nix-versions.oeiuwq.com/flake.zip/ruby@latest/nodejs@latest -o flake.zip

# Use directly with nix develop
nix develop 'https://nix-versions.oeiuwq.com/flake.zip/cowsay@latest/go@1.24.x' --no-write-lock-file
```

--------------------------------

### Search Nix Packages Using Wildcards

Source: https://github.com/vic/nix-versions/blob/main/docs/getting-started/finding-packages.md

Demonstrates how to use the wildcard character '*' in package names when searching with nix-versions, facilitated by its integration with nix-search-cli. This allows for broader searches when the exact package name is unknown.

```shell
# Search for packages whose names start with 'cargo'
nix run nixpkgs#nix-versions -- 'cargo-*'
```

--------------------------------

### Web Service Endpoints Reference

Source: https://context7.com/vic/nix-versions/llms.txt

Complete list of available HTTP endpoints provided by the nix-versions web service.

```APIDOC
## Web Service Endpoints Reference

Complete list of available HTTP endpoints provided by the nix-versions web service.

### Flake endpoints (recommended)

- **GET `/flake.nix/{package-specs}`**: Returns `flake.nix` content.
- **GET `/flake.zip/{package-specs}`**: Returns ZIP archive containing `flake.nix`.
```

--------------------------------

### List Packages by Program Wildcard (Bash)

Source: https://github.com/vic/nix-versions/blob/main/docs/getting-started/finding-packages.md

Allows listing packages that match a program name containing wildcards, such as '*'. This is helpful for finding related packages or a range of versions for a program.

```shell
#!/bin/bash
nix-shell -p nix-shell --run "nix-env -qaP --description 'cargo*'"

```

--------------------------------

### Search Packages with Wildcards in Nix Versions

Source: https://context7.com/vic/nix-versions/llms.txt

Illustrates using wildcard characters in package names with the Nix Versions CLI to find packages matching a pattern, such as all packages related to 'cargo' or 'python3'.

```bash
# Find all cargo-related packages
nix-versions 'cargo*'

# Find all python packages
nix-versions 'python3*'
```

--------------------------------

### Generate Non-Flake Nix Environments (default.nix)

Source: https://context7.com/vic/nix-versions/llms.txt

Generate experimental Nix environments using the `default.nix` endpoint. This provides a way to create reproducible environments without using flakes.

```bash
# Download generated default.nix
curl https://nix-versions.oeiuwq.com/default.nix/ruby@latest -o default.nix

# Use with nix-shell
nix-shell https://nix-versions.oeiuwq.com/default.zip/ruby@latest -A devShell

# The default.nix provides:
# - tools: attribute set with package metadata
# - nixpkgs: fetched nixpkgs for each tool
# - packages: the actual packages
# - pkgsEnv: buildEnv with all packages
# - devShell: mkShell with packages
```

--------------------------------

### List Packages by Program Name (Bash)

Source: https://github.com/vic/nix-versions/blob/main/docs/getting-started/finding-packages.md

Lists packages that provide a specific program by prefixing the program name with 'bin/'. This is useful for finding the exact package that contains an executable.

```shell
#!/bin/bash
nix-shell -p nix-shell --run "nix-env -qaP --description 'emacsclient'"

```

--------------------------------

### Using flake.zip with `nix develop`

Source: https://github.com/vic/nix-versions/blob/main/docs/flake-generator.md

Demonstrates how to use the `flake.zip` endpoint to create a temporary development environment with specified tools.

```APIDOC
## Using `nix develop` with `flake.zip`

### Description
Creates a quick one-shot development environment using the `flake.zip` endpoint. This allows you to enter a shell with the specified tools without needing to manage a local flake file.

### Command
```bash
nix develop https://nix-versions.oeiuwq.com/flake.zip/go@1.24.x/ruby@~3.4 --no-write-lock-file
```

### Parameters
- **URL**: The URL pointing to the `flake.zip` endpoint with the desired package specifications.
- **`--no-write-lock-file`**: Optional flag to prevent writing a `flake.lock` file.
```

--------------------------------

### Nix Shell Integration for Development Environments

Source: https://context7.com/vic/nix-versions/llms.txt

Integrate nix-versions with `nix shell` to create development environments with specific package versions. Supports entering shells with package lists or one-liners with inline specs.

```bash
# Enter a shell with specific package versions
nix shell $(nix-versions -ir .nix_tools)

# One-liner with inline specs
nix shell $(nix-versions --installable go@1.24.x ruby@latest)

# Install packages to a custom profile
mkdir -p ./tools
nix profile install --profile $PWD/tools/my-tools $(nix-versions -i cargo@latest glibc^static,dev@latest)
export PATH=$PWD/tools/my-tools/bin:$PATH
```

--------------------------------

### Nix Versions Web Service Endpoints Reference

Source: https://context7.com/vic/nix-versions/llms.txt

A reference for the available HTTP endpoints provided by the nix-versions web service. These endpoints allow for programmatic access to generated Nix configurations.

```bash
# Flake endpoints (recommended)
GET /flake.nix/{package-specs}    # Returns flake.nix content
GET /flake.zip/{package-specs}    # Returns ZIP with flake.nix
```

--------------------------------

### Direnv Helper Scripts

Source: https://context7.com/vic/nix-versions/llms.txt

These endpoints provide scripts to help integrate Nix tools with direnv.

```APIDOC
## GET /use_nix_tools.sh

### Description
Returns the base script for direnv integration with Nix tools.

### Method
GET

### Endpoint
/use_nix_tools.sh

### Response
#### Success Response (200)
- **script_content** (string) - The content of the direnv integration script.

## GET /use_nix_tools.sh/{specs}

### Description
Returns a direnv integration script pre-configured with the specified Nix installables.

### Method
GET

### Endpoint
/use_nix_tools.sh/{specs}

### Parameters
#### Path Parameters
- **specs** (string) - Required - A comma-separated list of Nix installables (e.g., `go/ruby/nodejs`).

### Response
#### Success Response (200)
- **script_content** (string) - The content of the pre-configured direnv integration script.
```

--------------------------------

### Non-flake Endpoints

Source: https://context7.com/vic/nix-versions/llms.txt

These endpoints provide default.nix content or a ZIP archive containing default.nix for specified package versions.

```APIDOC
## GET /default.nix/{package-specs}

### Description
Returns the content of the default.nix file for the specified package specifications.

### Method
GET

### Endpoint
/default.nix/{package-specs}

### Parameters
#### Path Parameters
- **package-specs** (string) - Required - A comma-separated list of package specifications (e.g., `go@1.24.x/ruby@~3.4`).

### Response
#### Success Response (200)
- **content** (string) - The content of the default.nix file.

## GET /default.zip/{package-specs}

### Description
Returns a ZIP archive containing the default.nix file for the specified package specifications.

### Method
GET

### Endpoint
/default.zip/{package-specs}

### Parameters
#### Path Parameters
- **package-specs** (string) - Required - A comma-separated list of package specifications (e.g., `nodejs@20.x`).

### Response
#### Success Response (200)
- **file** (binary) - A ZIP archive containing the default.nix file.
```

--------------------------------

### Generate flake.nix via HTTP Endpoint

Source: https://context7.com/vic/nix-versions/llms.txt

Generate a `flake.nix` file with version-pinned packages directly from an HTTP endpoint. This allows for easy creation of reproducible Nix flakes.

```bash
# Download generated flake.nix
curl https://nix-versions.oeiuwq.com/flake.nix/ruby@latest/nodejs@latest -o flake.nix

# Inspect the generated flake outputs
nix flake show https://nix-versions.oeiuwq.com/flake.zip/go@1.24.x/ruby@~3.4 --no-write-lock-file

# Generated flake structure:
# {
#   overlays.default          # Overlay with { ruby = ...; go = ...; }
#   packages.${system} = {
#     go = ...;               # Go at specified version
#     ruby = ...;             # Ruby at specified version
#     default = ...;          # buildEnv with all tools
#   };
#   devShells.${system} = {
#     default = ...;          # devshell with specified tools
#   };
# }
```

--------------------------------

### Flake Generator - With Devenv

Source: https://context7.com/vic/nix-versions/llms.txt

Use version-pinned packages as inputs in `devenv.yaml` configuration.

```APIDOC
## Flake Generator - With Devenv

Use version-pinned packages as inputs in `devenv.yaml` configuration.

### Example `devenv.yaml`:
```yaml
inputs:
  tools:
    url: "https://nix-versions.oeiuwq.com/flake.zip/go@~1.24/ruby@~3.4"
```
```

--------------------------------

### Generate Nix Flake for Tool Versions

Source: https://github.com/vic/nix-versions/blob/main/docs/README.md

This command shows how to use the `nix-versions` flake generator endpoint to create a reproducible development environment. It specifies tool versions like 'cowsay@latest' and 'go@1.24.x' and outputs a lock file, useful for CI/CD pipelines or team collaboration.

```shell
nix develop 'https://nix-versions.oeiuwq.com/flake.zip/cowsay@latest/go@1.24.x' --output-lock-file /dev/null
```

--------------------------------

### Flake Generator - flake.zip Endpoint

Source: https://context7.com/vic/nix-versions/llms.txt

Use the `flake.zip` endpoint as an input for your own flakes.

```APIDOC
## Flake Generator - flake.zip Endpoint

Use the `flake.zip` endpoint as an input for your own flakes.

### Example 1: Download as archive
```bash
curl https://nix-versions.oeiuwq.com/flake.zip/ruby@latest/nodejs@latest -o flake.zip
```

### Example 2: Use directly with nix develop
```bash
nix develop 'https://nix-versions.oeiuwq.com/flake.zip/cowsay@latest/go@1.24.x' --no-write-lock-file
```
```

--------------------------------

### Find Program Versions on Nix Channels (Bash)

Source: https://github.com/vic/nix-versions/blob/main/docs/getting-started/finding-packages.md

Searches for versions of a program on specific NixOS releases or nixpkgs branches using the Lazamar index. This enables finding versions from particular stable or unstable channels.

```shell
#!/bin/bash
nix-shell -p nix-shell --run "nix-env -qaP --description 'emacs' --channel 'nixos-21.05' --channel 'nixos-23.05' --channel 'nixpkgs-unstable'"

```

--------------------------------

### Utility Endpoint

Source: https://context7.com/vic/nix-versions/llms.txt

This endpoint retrieves the SRI hash for a given nixpkgs revision.

```APIDOC
## GET /nixpkgs-sri/{revision}

### Description
Retrieves the Subresource Integrity (SRI) hash for a specified nixpkgs revision.

### Method
GET

### Endpoint
/nixpkgs-sri/{revision}

### Parameters
#### Path Parameters
- **revision** (string) - Required - The nixpkgs revision (e.g., `nixos-23.11`).

### Response
#### Success Response (200)
- **sri_hash** (string) - The SRI hash for the given nixpkgs revision.
```

--------------------------------

### List Package Versions with SemVer Constraints

Source: https://github.com/vic/nix-versions/blob/main/docs/getting-started/listing-versions.md

This command filters package versions based on Semantic Versioning (SemVer) constraints. It allows specifying a range of release series, such as `emacs@~27 || ~29` to match versions 27.x and 29.x.

```shell
<!-- @include: ./emacs-27-29.ansi.bash -->
```

--------------------------------

### Flake Generator - flake.nix Endpoint

Source: https://context7.com/vic/nix-versions/llms.txt

Generate a `flake.nix` file with version-pinned packages via an HTTP endpoint.

```APIDOC
## Flake Generator - flake.nix Endpoint

Generate a `flake.nix` file with version-pinned packages via HTTP endpoint.

### Example 1: Download generated flake.nix
```bash
curl https://nix-versions.oeiuwq.com/flake.nix/ruby@latest/nodejs@latest -o flake.nix
```

### Example 2: Inspect generated flake outputs
```bash
nix flake show https://nix-versions.oeiuwq.com/flake.zip/go@1.24.x/ruby@~3.4 --no-write-lock-file
```

### Generated flake structure:
```json
{
  "overlays.default": "Overlay with { ruby = ...; go = ...; }",
  "packages.${system}": {
    "go": "Go at specified version",
    "ruby": "Ruby at specified version",
    "default": "buildEnv with all tools"
  },
  "devShells.${system}": {
    "default": "devshell with specified tools"
  }
}
```
```

--------------------------------

### Use Generated Flake as Input in flake.nix

Source: https://context7.com/vic/nix-versions/llms.txt

Incorporate version-pinned tools generated by nix-versions as inputs in your `flake.nix`. This ensures reproducible development environments with specific package versions.

```nix
# flake.nix
{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
    # Version-pinned tools as input
    tools.url = "https://nix-versions.oeiuwq.com/flake.zip/go@~1.24/pip@25";
  };

  outputs = { self, nixpkgs, tools }:
    {
    devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell {
      buildInputs = [
        tools.packages.x86_64-linux.go
        tools.packages.x86_64-linux.pip
      ];
    };
  };
}
```

--------------------------------

### Generate flake.nix and flake.zip with specified packages

Source: https://github.com/vic/nix-versions/blob/main/docs/flake-generator.md

These commands demonstrate how to fetch a `flake.nix` file or a `flake.zip` archive containing the latest versions of Ruby and Node.js. The `flake.zip` is useful as an input for other flakes.

```shell
# Generate a flake.nix containing latest ruby and nodejs.
curl https://nix-versions.oeiuwq.com/flake.nix/ruby@latest/nodejs@latest -o flake.nix

# An archive containing flake.nix. This is useful as input for your own flakes.
curl https://nix-versions.oeiuwq.com/flake.zip/ruby@latest/nodejs@latest -o flake.zip
```

--------------------------------

### Flake Generator - As Flake Input

Source: https://context7.com/vic/nix-versions/llms.txt

Use the generated flake as an input in your own `flake.nix` for version-pinned dependencies.

```APIDOC
## Flake Generator - As Flake Input

Use the generated flake as an input in your own `flake.nix` for version-pinned dependencies.

### Example `flake.nix`:
```nix
{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
    # Version-pinned tools as input
    tools.url = "https://nix-versions.oeiuwq.com/flake.zip/go@~1.24/pip@25";
  };

  outputs = { self, nixpkgs, tools }:
    {
      devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell {
        buildInputs = [
          tools.packages.x86_64-linux.go
          tools.packages.x86_64-linux.pip
        ];
      };
    };
}
```
```

--------------------------------

### Use generated flake.zip with nix develop

Source: https://github.com/vic/nix-versions/blob/main/docs/flake-generator.md

This command illustrates how to create a temporary development environment using `nix develop` with a `flake.zip` URL. It specifies versions for Go and Ruby and avoids writing a lock file.

```shell
nix develop https://nix-versions.oeiuwq.com/flake.zip/go@1.24.x/ruby@~3.4 --no-write-lock-file
```

--------------------------------

### Nix Shell Integration

Source: https://context7.com/vic/nix-versions/llms.txt

Integrate nix-versions with nix shell to create development environments with specific package versions.

```APIDOC
## Nix Shell Integration

Use nix-versions with nix shell to create development environments.

### Example 1: Enter a shell with specific package versions
```bash
nix shell $(nix-versions -ir .nix_tools)
```

### Example 2: One-liner with inline specs
```bash
nix shell $(nix-versions --installable go@1.24.x ruby@latest)
```

### Example 3: Install packages to a custom profile
```bash
mkdir -p ./tools
nix profile install --profile $PWD/tools/my-tools $(nix-versions -i cargo@latest glibc^static,dev@latest)
export PATH=$PWD/tools/my-tools/bin:$PATH
```
```

--------------------------------

### Using flake.zip as input in Nix Flakes

Source: https://github.com/vic/nix-versions/blob/main/docs/flake-generator.md

Shows how to reference the `flake.zip` endpoint as an input in your own `flake.nix` file to pin specific tool versions.

```APIDOC
## Using as `input` on your own flakes

### Description
Integrates the `flake.zip` endpoint as an input in your `flake.nix` to pin tools to specific versions. This ensures reproducible builds and allows for controlled updates.

### Example `flake.nix`
```nix
{ ... }

inputs.tools.url = "https://nix-versions.oeiuwq.com/flake.zip/go@~1.24";

outputs = inputs: {
  # Go 1.24 is available at:
  # inputs.tools.packages.${system}.go
};
```

### Parameters
- **`inputs.<name>.url`**: The URL of the `flake.zip` endpoint, followed by the package specifications.
```

--------------------------------

### Use Generated Flake with Devenv

Source: https://context7.com/vic/nix-versions/llms.txt

Configure devenv.yaml to use version-pinned packages from nix-versions as inputs. This simplifies the management of development environment dependencies.

```yaml
# devenv.yaml
inputs:
  tools:
    url: "https://nix-versions.oeiuwq.com/flake.zip/go@~1.24/ruby@~3.4"
```