flk-0.1.0 is not a library.

Visit the last successful build: flk-0.6.1

flk 🚀

A modern CLI tool for managing Nix flake development environments with the simplicity of Devbox

flk makes managing Nix flakes feel like using a package manager. No more manually editing flake.nix files—just use simple commands to add packages, create custom shell commands, and manage your development environment.

✨ Features

🎯 Smart Initialization - Auto-detects your project type (Rust, Python, Node.js, Go) and creates the right template
🔍 Package Search - Search nixpkgs directly from your terminal
📦 Easy Package Management - Add and remove packages with simple commands
⚡ Custom Shell Commands - Define reusable commands for your development workflow
🌍 Environment Variables - Manage environment variables through the CLI
🔒 Lock File Management - View, backup, and restore your flake.lock with ease
🎨 Language Templates - Pre-configured templates for popular languages and frameworks

📦 Installation

Prerequisites

Nix with flakes enabled
Rust 1.70+ (if building from source)

From Source

git clone https://github.com/AEduardo-dev/flk.git
cd flk
cargo build --release
sudo cp target/release/flk /usr/local/bin/

From Cargo (Coming Soon)

cargo install flk

With Nix

nix profile install github:AEduardo-dev/flk

🚀 Quick Start

1. Initialize Your Project

# Auto-detect project type and create flake.nix
flk init

# Or specify a template
flk init --template rust
flk init --template python
flk init --template node
flk init --template go

Supported auto-detection:

Cargo.toml → Rust template
package.json → Node.js template
pyproject.toml or requirements.txt → Python template
go.mod → Go template

2. Add Packages

# Search for packages
flk search ripgrep

# Get detailed package info
flk deep-search ripgrep --versions

# Add packages to your environment
flk add ripgrep
flk add git
flk add neovim

3. Add Custom Commands

# Add inline commands
flk add-command test "cargo test --all"
flk add-command dev "npm run dev"

# Source commands from a file
flk add-command scripts --file ./scripts/dev.sh

4. Manage Environment Variables

# Add environment variables
flk env add DATABASE_URL "postgresql://localhost/mydb"
flk env add API_KEY "your-api-key"

# List all environment variables
flk env list

# Remove an environment variable
flk env remove API_KEY

5. Enter Your Development Environment

nix develop

Your custom commands and environment variables will be automatically available!

📖 Command Reference

Project Management

`flk init [OPTIONS]`

Initialize a new flake.nix in the current directory.

Options:

-t, --template <TYPE> - Project type: rust, python, node, go, or generic
-f, --force - Overwrite existing flake.nix

Examples:

flk init                    # Auto-detect project type
flk init --template rust    # Use Rust template
flk init --force            # Overwrite existing flake.nix

`flk show`

Display the contents and configuration of your flake.nix in a human-readable format.

flk show

`flk list`

List all packages in your development environment.

flk list

Package Management

`flk search <QUERY> [OPTIONS]`

Search for packages in nixpkgs.

Options:

-l, --limit <NUMBER> - Limit number of results (default: 10)

Examples:

flk search ripgrep
flk search python --limit 20

`flk deep-search <PACKAGE> [OPTIONS]`

Get detailed information about a specific package.

Options:

-v, --versions - Show version pinning information

Examples:

flk deep-search ripgrep
flk deep-search python311 --versions

`flk add <PACKAGE>`

Add a package to your flake.nix.

Examples:

flk add ripgrep
flk add git
flk add nodejs

Note: Version pinning is planned for a future release (see issue #5).

`flk remove <PACKAGE>`

Remove a package from your flake.nix.

Examples:

flk remove ripgrep

Custom Commands

`flk add-command <NAME> <COMMAND> [OPTIONS]`

Add a custom shell command to your development environment.

Options:

-f, --file <PATH> - Source commands from a file

Examples:

# Inline command
flk add-command test "cargo test --all"
flk add-command dev "npm run dev -- --watch"

# Multi-line command
flk add-command deploy "cargo build --release && scp target/release/app server:/opt/"

# Source from file
flk add-command scripts --file ./dev-scripts.sh

Command naming rules:

Must contain only letters, numbers, hyphens, and underscores
Cannot start with a hyphen
Examples: test, dev-server, build_prod

`flk remove-command <NAME>`

Remove a custom command from your dev shell.

Examples:

flk remove-command test

Environment Variables

`flk env add <NAME> <VALUE>`

Add an environment variable to your dev shell.

Examples:

flk env add DATABASE_URL "postgresql://localhost:5432/mydb"
flk env add NODE_ENV "development"
flk env add API_KEY "sk-..."

Variable naming rules:

Must start with a letter or underscore
Can only contain letters, numbers, and underscores
Examples: MY_VAR, _private, API_KEY_2

`flk env remove <NAME>`

Remove an environment variable from your dev shell.

Examples:

flk env remove DATABASE_URL

`flk env list`

List all environment variables in your dev shell.

flk env list

Lock File Management

`flk lock show`

Display detailed information about your flake.lock file.

flk lock show

`flk lock history`

Show backup history of your lock file.

flk lock history

`flk lock restore <BACKUP>`

Restore a previous version of your lock file.

Examples:

flk lock restore latest                    # Restore most recent backup
flk lock restore 2025-01-27_14-30-00      # Restore specific backup

Updates

`flk update [OPTIONS]`

Update all flake inputs to their latest versions.

Options:

--show - Preview updates without applying them

Examples:

flk update              # Update all inputs
flk update --show       # Preview available updates

Note: A backup of your flake.lock is automatically created before updating.

💡 Usage Examples

Python Data Science Environment

flk init --template python
flk add python311Packages.numpy
flk add python311Packages.pandas
flk add python311Packages.matplotlib
flk add jupyter

flk add-command notebook "jupyter notebook --port=8888"
flk env add JUPYTER_CONFIG_DIR "./.jupyter"

nix develop
notebook  # Your custom command is ready!

Rust Web Development

flk init --template rust
flk add postgresql
flk add redis

flk add-command dev "cargo watch -x run"
flk add-command migrate "sqlx migrate run"
flk env add DATABASE_URL "postgresql://localhost/myapp"

nix develop
dev      # Start development server with auto-reload
migrate  # Run database migrations

Node.js Full-Stack Project

flk init --template node
flk add postgresql
flk add docker-compose

flk add-command dev "npm run dev"
flk add-command db "docker-compose up -d postgres"
flk env add NODE_ENV "development"

nix develop
db   # Start database
dev  # Start development server

Go Microservice

flk init --template go
flk add protobuf
flk add grpcurl

flk add-command build "go build -o bin/service ./cmd/service"
flk add-command proto "protoc --go_out=. --go-grpc_out=. api/*.proto"
flk env add GO_ENV "development"

nix develop
proto  # Generate protobuf code
build  # Build the service

🛠️ Development

Prerequisites

Rust 1.70+
Nix with flakes enabled

Building

git clone https://github.com/AEduardo-dev/flk.git
cd flk
cargo build

Running Tests

# Run all tests
cargo test

# Run integration tests
cargo test --test integration_tests

# Run with output
cargo test -- --nocapture

Installing Locally

cargo install --path .

🏗️ Project Structure

flk/
├── src/
│   ├── main.rs              # CLI entry point
│   ├── commands/            # Command implementations
│   │   ├── init.rs          # Initialize flake
│   │   ├── add.rs           # Add packages
│   │   ├── remove.rs        # Remove packages
│   │   ├── search.rs        # Search packages
│   │   ├── add_command.rs   # Add custom commands
│   │   ├── remove_command.rs
│   │   ├── env.rs           # Environment variable management
│   │   ├── lock.rs          # Lock file management
│   │   ├── update.rs        # Update flake inputs
│   │   ├── show.rs          # Display flake config
│   │   └── list.rs          # List packages
│   ├── flake/               # Flake parsing and generation
│   │   ├── parser.rs        # Parse flake.nix
│   │   ├── generator.rs     # Generate flake.nix
│   │   └── interface.rs     # Data structures
│   ├── nix/                 # Nix command wrappers
│   │   └── mod.rs
│   └── utils/               # Utility functions
│       └── backup.rs        # Backup management
├── templates/               # Flake templates
│   ├── default_flake.nix
│   ├── rust_flake.nix
│   ├── python_flake.nix
│   ├── node_flake.nix
│   └── go_flake.nix
└── tests/                   # Test files
    ├── integration_tests.rs
    └── unit_tests.rs

🗺️ Roadmap

Project scaffolding and CLI structure
Implement init command with auto-detection
Implement search and deep-search commands
Implement add and remove commands
Implement add-command and remove-command
Implement env subcommands
Implement lock file management
Implement update, show, and list commands
Documentation and examples
Package version pinning (#5)
CI/CD and releases
Publish to crates.io
Interactive TUI mode
Flake templates marketplace
Plugin system

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

How to Contribute

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

🐛 Bug Reports

If you find a bug, please open an issue with:

A clear description of the problem
Steps to reproduce
Expected vs actual behavior
Your environment (OS, Nix version, etc.)

🔗 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

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

The Nix community for creating an amazing ecosystem
Jetify for the Devbox inspiration and showing what's possible
All contributors and users of flk

📞 Support

📧 Open an issue for bug reports or feature requests
💬 Start a discussion for questions or ideas
⭐ Star the repository if you find it useful!

Made with ❤️ by AEduardo-dev

Note: This project is under active development (v0.1.0). While all core features are implemented and working, some advanced features like version pinning are still in progress. See the roadmap for details.

flk 0.1.0

flk 🚀

✨ Features

📦 Installation

Prerequisites

From Source

From Cargo (Coming Soon)

With Nix

🚀 Quick Start

1. Initialize Your Project

2. Add Packages

3. Add Custom Commands

4. Manage Environment Variables

5. Enter Your Development Environment

📖 Command Reference

Project Management

flk init [OPTIONS]

flk show

flk list

Package Management

flk search <QUERY> [OPTIONS]

flk deep-search <PACKAGE> [OPTIONS]

flk add <PACKAGE>

flk remove <PACKAGE>

Custom Commands

flk add-command <NAME> <COMMAND> [OPTIONS]

flk remove-command <NAME>

Environment Variables

flk env add <NAME> <VALUE>

flk env remove <NAME>

flk env list

Lock File Management

flk lock show

flk lock history

flk lock restore <BACKUP>

Updates

flk update [OPTIONS]

💡 Usage Examples

Python Data Science Environment

Rust Web Development

Node.js Full-Stack Project

Go Microservice

🛠️ Development

Prerequisites

Building

Running Tests

Installing Locally

🏗️ Project Structure

🗺️ Roadmap

🤝 Contributing

How to Contribute

🐛 Bug Reports

🔗 Related Projects

📄 License

🙏 Acknowledgments

📞 Support

`flk init [OPTIONS]`

`flk show`

`flk list`

`flk search <QUERY> [OPTIONS]`

`flk deep-search <PACKAGE> [OPTIONS]`

`flk add <PACKAGE>`

`flk remove <PACKAGE>`

`flk add-command <NAME> <COMMAND> [OPTIONS]`

`flk remove-command <NAME>`

`flk env add <NAME> <VALUE>`

`flk env remove <NAME>`

`flk env list`

`flk lock show`

`flk lock history`

`flk lock restore <BACKUP>`

`flk update [OPTIONS]`