# Nickel Installation Guide\n\n## Overview\n\nNickel is a configuration language that complements KCL in the provisioning system. It provides:\n\n- Lazy evaluation for efficient configuration processing\n- Modern functional programming paradigms\n- Excellent integration with the CLI daemon for config rendering\n\n## Installation Methods\n\n### Recommended: Nix (Official Method)\n\nNickel is maintained by Tweag and officially recommends Nix for installation. This avoids all dependency issues:\n\n```\n# Install Nix (one-time setup) - Using official NixOS installer\ncurl https://nixos.org/nix/install | sh\n\n# Install Nickel via Nix\nnix profile install nixpkgs#nickel\n\n# Verify installation\nnickel --version\n```\n\n**Why Nix?**\n\n- Isolated, reproducible environments\n- No system library conflicts\n- Official Nickel distribution method\n- Works on macOS, Linux, and other Unix-like systems\n- Pre-built binaries available\n\n### Alternative: Automatic Installation\n\nThe provisioning system can automate installation:\n\n```\n# Via tools-install script (uses Nix if available)\n$PROVISIONING/core/cli/tools-install nickel\n\n# Check installation status\n$PROVISIONING/core/cli/tools-install check\n```\n\n### Alternative: Manual Installation from Source\n\nIf you have a Rust toolchain:\n\n```\ncargo install nickel-lang-cli\n```\n\n**Note**: This requires Rust compiler (slower than pre-built binaries)\n\n## Troubleshooting\n\n### "Library not loaded: /nix/store/..." Error\n\nThis occurs when using pre-built binaries without Nix installed. **Solution**: Install Nix or use Cargo:\n\n```\n# Option 1: Install Nix (recommended) - Using official NixOS installer\ncurl https://nixos.org/nix/install | sh\n\n# Then install Nickel\nnix profile install nixpkgs#nickel\n\n# Option 2: Build from source with Cargo\ncargo install nickel-lang-cli\n```\n\n### Command Not Found\n\nEnsure Nix is properly installed and in PATH:\n\n```\n# Check if Nix is installed\nwhich nix\n\n# If not found, install Nix first using official NixOS installer:\ncurl https://nixos.org/nix/install | sh\n\n# Then install Nickel\nnix profile install nixpkgs#nickel\n```\n\n### Version Mismatch\n\nTo ensure you're using the correct version:\n\n```\n# Check installed version\nnickel --version\n\n# Expected version (from provisioning/core/versions)\necho $NICKEL_VERSION\n\n# Update to latest\nnix profile upgrade '*'\n```\n\n## Integration with Provisioning System\n\n### CLI Daemon Integration\n\nNickel is integrated into the CLI daemon for configuration rendering:\n\n```\n# Render Nickel configuration via daemon\ncurl -X POST http://localhost:9091/config/render \\n  -H "Content-Type: application/json" \\n  -d '{\n    "language": "nickel",\n    "content": "{name = \"my-config\", enabled = true}",\n    "context": {"env": "prod"}\n  }'\n```\n\n### Comparison with KCL\n\n| Feature | KCL | Nickel |\n| --------- | ----- | -------- |\n| **Type System** | Gradual, OOP-style | Gradual, Functional |\n| **Evaluation** | Eager | Lazy (partial evaluation) |\n| **Performance** | Fast | Very fast (lazy) |\n| **Learning Curve** | Moderate | Functional programming knowledge helps |\n| **Use Cases** | Infrastructure schemas | Configuration merging, lazy evaluation |\n\n## Deployment Considerations\n\n### macOS M1/M2/M3 (arm64)\n\nNix automatically handles architecture:\n\n```\nnix profile install nixpkgs#nickel\n# Automatically installs arm64 binary\n```\n\n### Linux (x86_64/arm64)\n\n```\nnix profile install nixpkgs#nickel\n# Automatically installs correct architecture\n```\n\n### CI/CD Environments\n\nFor GitHub Actions or other CI/CD:\n\n```\n# .github/workflows/example.yml\n- name: Install Nickel\n  run: |\n    curl https://nixos.org/nix/install | sh\n    nix profile install nixpkgs#nickel\n```\n\n## Resources\n\n- **Official Website**: <https://nickel-lang.org>\n- **Getting Started**: <https://nickel-lang.org/getting-started>\n- **User Manual**: <https://nickel-lang.org/user-manual>\n- **GitHub**: <https://github.com/tweag/nickel>\n- **Nix Package**: <https://search.nixos.org/packages?query=nickel>\n\n## Version Information\n\nCurrent provisioning system configuration:\n\n```\n# View configured version\ncat $PROVISIONING/core/versions | grep NICKEL_VERSION\n\n# Current: 1.15.1\n```\n\n## Support\n\nFor issues related to:\n\n- **Nickel language**: See <https://github.com/tweag/nickel/issues>\n- **Nix installation**: See <https://github.com/DeterminateSystems/nix-installer>\n- **Provisioning integration**: See the provisioning system documentation
