nixkit Configuration Options

Enable the module and define basic preferences. The module will automatically install Raycast Beta (0.61.0.0) to /Applications/Raycast Beta.app:

programs.raycast = {
  enable = true;

  preferences = {
    general.globalHotkey = "Option-49";
    appearance = {
      textSize = "medium";
      statusBarVisible = true;
    };
  };

  snippets = [
    {
      name = "Email Signature";
      text = "user@example.com";
      keyword = "email";
    }
  ];
};

Note: Raycast is unfree software. Ensure your NixOS configuration allows unfree packages:

nixpkgs.config.allowUnfree = true;

After running home-manager switch, import the generated configuration:

# Automated import (requires Accessibility permissions)
raycast-import-config

# Manual import
# 1. Open Raycast
# 2. Navigate to Settings → Advanced → Import Settings & Data
# 3. Select ~/.config/raycast/import.rayconfig

Define Raycast settings directly in Nix using structured options. This approach provides type safety and validation.

programs.raycast = {
  enable = true;
  version = "1.79.1";

  preferences = {
    general = {
      globalHotkey = "Command-49";
      alternativeEscape = false;
    };

    appearance = {
      statusBarVisible = true;
      textSize = "medium";        # Options: "small" | "medium" | "large"
      windowMode = "default";     # Options: "default" | "compact"
      showFavoritesInCompactMode = true;
    };

    advanced = {
      navigationStyle = "macos";
      popToRootTimeout = 90;
      keepWindowVisibleOnResign = false;
    };
  };

  snippets = [
    {
      name = "Shrug";
      text = "¯\\_(ツ)_/¯";
      keyword = "shrug";
    }
  ];

  fallbackSearches = [
    "builtin_command_fileSearch_fallbackSearch"
    "builtin_command_searchEmoji_fallbackSearch"
  ];

  encryptionPassword = "your-password";  # Optional
};

Import an existing Raycast export. This is the recommended approach for migrating existing configurations.

programs.raycast = {
  enable = true;
  configFile = ./raycast-config.json;
  
  # Re-encrypt with a different password (optional)
  encryptionPassword = "new-password";
};

Use Nix expressions to load and manipulate configuration programmatically.

programs.raycast = {
  enable = true;
  settings = builtins.fromJSON (builtins.readFile ./raycast-export.json);
  encryptionPassword = "password";
};

Extend the configuration with custom package settings:

programs.raycast = {
  enable = true;
  preferences.general.globalHotkey = "Option-49";
  
  extraConfig = {
    builtin_package_github = {
      provider_schemaVersion = 1;
      repositories = ["owner/repo1" "owner/repo2"];
    };
    builtin_package_linear = {
      provider_schemaVersion = 1;
      teamIds = ["team-id-1"];
    };
  };
};

Decrypt and inspect .rayconfig files.

Syntax:

raycast-decrypt-config <input.rayconfig> [password] [output.json]

Examples:

# Decrypt with default password
raycast-decrypt-config export.rayconfig

# Decrypt with custom password
raycast-decrypt-config export.rayconfig mysecret output.json

# Process unencrypted file
raycast-decrypt-config export.rayconfig "" output.json

The decrypted JSON can be used with configFile or modified and re-imported.

Create .rayconfig files from JSON configuration.

Syntax:

raycast-encrypt-config <input.json> [password] [output.rayconfig]

Examples:

# Create unencrypted .rayconfig
raycast-encrypt-config config.json

# Create encrypted .rayconfig
raycast-encrypt-config config.json your-password

# Specify custom output path
raycast-encrypt-config config.json password output.rayconfig

Automate the Raycast import process using AppleScript. Available only when the module is enabled.

Syntax:

raycast-import-config

This utility:

Requirements:

Configuration:

programs.raycast = {
  automationHotkey = "option down";  # Must match Raycast global hotkey
};

Hotkey Values:

Convert the .rayconfig file to JSON:

raycast-decrypt-config ~/Downloads/Raycast-2026-05-27.rayconfig [password]

This produces Raycast-2026-05-27.json containing the configuration data.

Reference the decrypted JSON in your configuration:

programs.raycast = {
  enable = true;
  configFile = ./Raycast-2026-05-27.json;
  
  # Optionally re-encrypt with a new password
  encryptionPassword = "new-password";
};

Alternatively, use an attribute set for programmatic manipulation:

programs.raycast = {
  enable = true;
  settings = builtins.fromJSON (builtins.readFile ./Raycast-2026-05-27.json);
};

These options are mutually exclusive, with priority order: configFile > settings > declarative options.

The .rayconfig file is a gzipped JSON file with the following structure:

{
  "exportedAt": "2026-05-27T06:38:52.663Z",
  "appVersion": "0.61.0.0",
  "osName": "macOS",
  "osVersion": "26.5.0",
  "osArch": "arm64",
  "schemaVersion": 2,
  "data": "<hex-encoded encrypted data>",
  "encryption": {
    "iv": "<hex-encoded initialization vector>",
    "salt": "<hex-encoded salt>",
    "authTag": "<hex-encoded authentication tag>"
  }
}

When encryption is enabled:

For unencrypted configurations:

Both encrypted and unencrypted .rayconfig files can be imported by Raycast.

Module not found or import errors

Ensure nixkit is properly added to your flake inputs and imported in your Home Manager configuration:

imports = [ nixkit.homeManagerModules.default ];

Python dependency errors

The module requires Python 3 with the cryptography library. This is automatically provided by Nix and should not require manual intervention.

Automated import not working

Import fails with decryption error

If Raycast reports a decryption error:

Wrong password

Ensure you’re using the correct password from the original export:

raycast-decrypt-config export.rayconfig CORRECT_PASSWORD output.json

Corrupted file

Verify the file is valid gzipped JSON:

gunzip -c export.rayconfig | jq empty

Settings not applying

The module generates .rayconfig files but does not automatically import them. You must:

Encryption password stored in plain text

The encryptionPassword option stores the password in the Nix store, which is world-readable. Consider:

The encryptionPassword option stores passwords in the Nix store, which is world-readable. This presents several security implications:

Recommendations:

Raycast configurations may contain:

Review your configuration before committing it to version control or sharing publicly.