flk 0.6.3 - Docs.rs

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

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 for a full walkthrough.

📦 Installation

Prerequisites: Nix with flakes enabled — recommended via Lix or the Determinate installer.

Method	Command
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
Cachix	`cachix use flk-cache` (prebuilt Nix binaries)

For Nix flake input, overlay, and Home Manager options see the Installation guide.

Shell Hook (optional)

Enable hot-reload (refresh) and profile switching (switch):

eval "$(flk hook bash)"   # or zsh; Fish: flk hook fish | source

📖 Commands

Command	Description
`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

🐦 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

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 for project structure, testing details, and CI info.

📚 Documentation

Resource	Link
User Guide (mdBook)	pixel-racks.gitlab.io/flk
API Reference	docs.rs/flk

Build locally:

# 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

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for details. For bugs, please open an issue with reproduction steps and environment info.

🔗 Related Projects

Devbox — Instant, portable dev environments (inspiration for flk)
devenv — Fast, declarative developer environments
Flox — Developer environments you can take with you
direnv — Shell extension for loading environments

📄 License

MIT — see LICENSE for details.

🙏 Acknowledgments

The Nix community for creating an amazing ecosystem
Jetify for the Devbox inspiration
Special mention to @vic for nix-versions
All contributors and users of flk — the flock keeps growing

Made with ❤️ (and a snowflake) by AEduardo-dev