<p align="center">
<img src="assets/banner.png" alt="flk — with Flik the flake-keeper" width="640" />
</p>
<p align="center">
<em>A flake manager that herds your inputs into a flock.</em>
</p>
<p align="center">
<a href="https://crates.io/crates/flk"><img alt="Crates.io" src="https://img.shields.io/crates/v/flk.svg" /></a>
<a href="https://gitlab.com/pixel-racks/flk/-/pipelines"><img alt="pipeline" src="https://gitlab.com/pixel-racks/flk/badges/main/pipeline.svg" /></a>
<a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg" /></a>
<a href="https://www.rust-lang.org"><img alt="Rust" src="https://img.shields.io/badge/rust-1.83%2B-blue.svg" /></a>
<a href="https://gitlab.com/pixel-racks/flk/-/pipelines"><img alt="coverage" src="https://gitlab.com/pixel-racks/flk/badges/main/coverage.svg?job=coverage" /></a>
</p>
---
**flk** makes managing Nix flakes feel like using a package manager. No more hand-editing `flake.nix` — just simple commands to add packages, define custom shell commands, and manage your development environment.
It's also where **Flik** lives. Flik is the little magenta bird up top: every flake `flk` builds is, under the hood, a flock of inputs — `nixpkgs` over here, your shell-lib over there, a pinned overlay tucked in the corner. `flk` is the manager that keeps that flock together; Flik is the one who carries the snowflake.
## ✨ Features
- 🎯 **Smart Initialization** — Auto-detects your project type (Rust, Python, Node.js, Go)
- 📦 **Easy Package Management** — Add/remove packages, pin specific versions
- ⚡ **Custom Shell Commands** — Define reusable commands for your workflow
- 🌍 **Environment Variables** — Manage per-project variables through the CLI
- 👤 **Multi-Profile Support** — Maintain separate flocks (profiles) inside one project
- 🔒 **Lock File Management** — Backup, preview, and restore your `flake.lock`
- 🐳 **Container Export** — Export environments to Docker, Podman, or JSON
- 🔄 **Hot Reload** — Shell hooks for instant `refresh` and `switch` between profiles
- 🐦 **Flik is watching** — Long-running ops get a multi-line ASCII Flik animation; failures land in his cool/half-lidded pose, successes get a wing-up hop
## ⚡ Quick Start
```bash
cargo install flk # install via cargo (or see table below)
flk init # scaffold a flake (auto-detects language)
flk add ripgrep # add a package — Flik fetches the pin
flk cmd add test "cargo test --all"
flk env add DB_URL "postgres://localhost/dev"
flk activate # enter the dev shell
```
See the [Getting Started guide](https://pixel-racks.gitlab.io/flk/getting-started.html) for a full walkthrough.
## 📦 Installation
**Prerequisites:** [Nix](https://nixos.org/download.html) with flakes enabled — recommended via [Lix](https://lix.systems/install/) or the [Determinate installer](https://determinate.systems/nix-installer/).
| **Cargo** | `cargo install flk` |
| **Nix (run)** | `nix run gitlab:pixel-racks/flk#flk` |
| **Nix (install)** | `nix profile install gitlab:pixel-racks/flk#flk` |
| **From source** | `git clone … && cd flk && cargo install --path .` |
| **Binaries** | [GitLab Releases](https://gitlab.com/pixel-racks/flk/-/releases) |
| **Cachix** | `cachix use flk-cache` (prebuilt Nix binaries) |
For Nix flake input, overlay, and Home Manager options see the [Installation guide](https://pixel-racks.gitlab.io/flk/installation.html).
### Shell Hook (optional)
Enable hot-reload (`refresh`) and profile switching (`switch`):
```sh
## 📖 Commands
| `flk init` | Initialize a new flake environment |
| `flk add` / `remove` | Add or remove packages (`--version` to pin) |
| `flk search` / `deep-search` | Search nixpkgs |
| `flk list` / `show` | List packages or pretty-print full config |
| `flk cmd add\|remove\|list` | Manage custom shell commands |
| `flk env add\|remove\|list` | Manage environment variables |
| `flk profile add\|remove\|list\|set-default` | Manage profiles (flocks-within-a-flock) |
| `flk activate` | Enter the dev shell |
| `flk update` | Update flake inputs (auto-backup) |
| `flk lock show\|history\|restore` | Manage flake.lock snapshots |
| `flk export` | Export to Docker, Podman, or JSON |
| `flk direnv init\|attach\|detach` | Direnv integration |
| `flk hook <shell>` | Generate shell hooks |
| `flk completions` | Generate shell completions |
Most commands accept `-p, --profile <NAME>` to target a specific profile.
Full command reference → [Commands documentation](https://pixel-racks.gitlab.io/flk/commands/overview.html)
## 🐦 Meet Flik
Flik is the mascot. The name is a one-letter cousin of `flk`, the way Ferris is to Rust or the Gopher is to Go — short, lowercase tool name, friendly named face. The snowflake on his head is a *flake* (the Nix kind), and the joke runs deeper than the costume: a `flk`-managed project gathers many sources into one cohesive flock of inputs. `flk` herds; Flik carries the flake.
You'll see two of his poses in the CLI:
- **Thinking** — the default. Snowflake assembling above his head while work runs.
- **Flock** — for ops that fan out (e.g. `flk export` streaming image layers). Birds cross the line; on success they land in a chevron V.
`NO_COLOR=1` strips the magenta. The art still works.
## 🛠️ Development
```bash
git clone https://gitlab.com/pixel-racks/flk.git && cd flk
nix develop # or ensure Rust 1.83+ is available
cargo build # debug build
cargo test # all tests
cargo fmt --all -- --check && cargo clippy -- -D warnings # lint
```
See the [Development guide](https://pixel-racks.gitlab.io/flk/development.html) for project structure, testing details, and CI info.
## 📚 Documentation
| **User Guide** (mdBook) | [pixel-racks.gitlab.io/flk](https://pixel-racks.gitlab.io/flk/) |
| **API Reference** | [docs.rs/flk](https://docs.rs/flk) |
**Build locally:**
```bash
# User guide — serve with live reload
cd flk-book && mdbook serve # http://localhost:3000
# Rust API docs
cargo doc --no-deps --open
# Both via Nix
nix build .#docs
```
## 🗺️ Roadmap
[Roadmap](https://gitlab.com/pixel-racks/flk/-/issues/6)
## 🤝 Contributing
Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
For bugs, please open an [issue](https://gitlab.com/pixel-racks/flk/-/issues) with reproduction steps and environment info.
## 🔗 Related Projects
- [Devbox](https://github.com/jetify-com/devbox) — Instant, portable dev environments (inspiration for flk)
- [devenv](https://devenv.sh/) — Fast, declarative developer environments
- [Flox](https://flox.dev/) — Developer environments you can take with you
- [direnv](https://direnv.net/) — Shell extension for loading environments
## 📄 License
MIT — see [LICENSE](LICENSE) for details.
## 🙏 Acknowledgments
- The Nix community for creating an amazing ecosystem
- Jetify for the Devbox inspiration
- Special mention to @vic for [nix-versions](https://github.com/vic/nix-versions)
- All contributors and users of flk — the flock keeps growing
---
**Made with ❤️ (and a snowflake) by [AEduardo-dev](https://gitlab.com/AEduardo-dev)**