comma

comma is available in nixpkgs.

Recommended: NixOS Configuration

Add comma to your systemPackages in your NixOS configuration:

Alternative: Nix Environment

Install it in your nix environment (not recommended):

Database Requirement

You must have the required nix-index database. You can download it ad-hoc following the nix-index-database instructions.

Alternatively, you can enable the database via the nix-index-database module using programs.nix-index-database.comma.enable. If you use this module, do not add comma to systemPackages manually.

environment.systemPackages = with pkgs; [ comma ];

The comma CLI allows you to run any executable found in the Nix ecosystem without manually managing Nix shells or installations. It searches the nix-index database, allows you to pick a specific derivation if multiple exist, and then executes the command within a temporary Nix environment.

Basic Usage

To run a command (e.g., htop), simply pass it as an argument:

comma htop

If the command has arguments, pass them after the command name:

comma htop -u

Key Features

• Picker Support: If multiple packages provide the same command, comma uses a picker (defaulting to fzy) to let you choose the correct derivation.
• Manpage Integration: Use the Man subcommand to view the manpage of a command within a Nix shell instead of running it.
• Confirmation: Use the --ask flag to prompt for confirmation before executing a command.

To optimize performance, comma caches derivation choices and path evaluations. You can control this behavior using the --cache-level flag or by managing the cache directly.

Cache Levels

• Level 0: Disables all caching.
• Level 1: Enables caching for derivation choices (the result of the picker).
• Level 2 (Default): Enables caching for both derivation choices and path evaluations (the actual Nix store paths).

Cache Maintenance

• Clear all cache: Use --empty-cache to wipe the entire cache.
• Delete specific entry: Use --delete-entry <command> to remove a specific command from the cache. This is useful if a cached derivation is no longer valid or you want to re-pick it.

Environment Variable

Set COMMA_CACHING to configure the default cache level.

comma uses the XDG Base Directory Specification to manage its cache. The cache file, which stores command choices and paths, is located in the user's state directory under comma/choices.

On Linux systems, this typically corresponds to ~/.local/state/comma/choices.

comma can cache both choices (the selected derivation for a command) and paths (the evaluated Nix path).

Caching paths (level 2) significantly improves performance for subsequent runs but may result in running older versions of a command if the Nix garbage collector has not run. If you need to ensure you are running the most up-to-date version, use cache level 1.

You can control caching using the --cache-level CLI flag or the COMMA_CACHING environment variable.

Cache Levels:

• 0: Completely disables caching.
• 1: Only caches choices.
• 2 (default): Caches both choices and paths.

You can generate shell completion files for comma using the --print-completions flag followed by the name of the shell you are using (e.g., bash, zsh, fish).

comma --print-completions bash > ~/.bash_completion.d/comma

To run a command using comma, prefix the command with a comma (,). This will resolve the command to its corresponding package in nixpkgs and run it via nix shell.

, cowsay neato

Instead of running a program, you can use comma to open its manpage within a Nix shell. This is useful for exploring documentation for tools you haven't installed locally.

To view the manpage for a command (e.g., ls), use the Man subcommand:

comma Man ls

Use check_database_updated() to check if the nix-index database is out of date. The function considers the database 'old' if it is more than 30 days old.

Behavioral Notes:

• If the database file is read-only (e.g., it is part of the Nix store), the function assumes the user is responsible for updates and will not issue a warning.
• If the database is older than 30 days and is writable, it prints a warning to stderr with instructions to obtain a prebuilt database or update via nix run 'nixpkgs#nix-index' --extra-experimental-features 'nix-command flakes'.

pub fn check_database_updated()

Use check_database_exists() to verify if the nix-index database file is present on the system. If the database does not exist, the function prints a warning to stderr suggesting that the user either obtain a prebuilt database from https://github.com/nix-community/nix-index-database or update it using nix run 'nixpkgs#nix-index' --extra-experimental-features 'nix-command flakes'. The function returns Ok(()) if the file exists, or Err(()) if it is missing.

pub fn check_database_exists() -> Result<(), ()>