flk 0.7.0

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
• 🌐 Global Mode — Machine-wide environment for always-on tools (flk global add ripgrep)
• 🐦 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.

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

Most commands accept -p, --profile <NAME> to target a specific profile.

Full command reference → Commands documentation

🌐 Global Packages

Keep daily tools (ripgrep, fd, bat, …) in one reproducible machine-wide environment — no more nix profile install or Homebrew drift:

flk global add ripgrep     # auto-initializes ~/.config/flk/global on first use
flk global add fd
flk global list            # review installed global tools
flk global remove fd
flk global activate        # enter the global dev shell

Want your global tools in every shell, including project shells? Eval the shellenv snippet in your rc file (appended to PATH, so project packages always win):

eval "$(flk global shellenv zsh)"      # .zshrc / .bashrc (use: bash)
flk global shellenv fish | source      # config.fish

The global environment is a regular flk project stored at ~/.config/flk/global (respects $XDG_CONFIG_HOME; override with FLK_GLOBAL_DIR), so it supports profiles (flk global profile add cli-tools), version pins, and updates (flk global update) like any project.

To land in your global tools shell for scripting or shell startup:

flk global activate                          # interactive global shell
nix develop "$(flk global path)#generic"     # equivalent raw nix invocation

🐦 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

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