FLI

A powerful, type-safe CLI library for Rust inspired by commander.js, designed to make building command-line applications intuitive and ergonomic.

Note: Version 1.0.0 includes breaking changes. See the Migration Guide for upgrading from v0.x.

Features

• 🎯 Type-safe value parsing with compile-time guarantees
• 🌲 Hierarchical commands with subcommand support
• 🎨 Beautiful help output with automatic formatting
• 🔧 Flexible option types: flags, required/optional values, single/multiple values
• 🚀 Zero-cost abstractions with minimal overhead
• 📦 Cargo.toml integration for automatic metadata
• ⚡ Error handling with detailed, actionable messages

Quick Start

[dependencies]

fli = "1.0"

use fli::{Fli, ValueTypes, Value};

fn main() {
    let mut app = Fli::new("myapp", "1.0.0", "A sample CLI app");
    
    // Add a simple flag
    app.add_option(
        "verbose",
        "Enable verbose output",
        "-v",
        "--verbose",
        ValueTypes::None
    );
    
    // Add an option that requires a value
    app.add_option(
        "name",
        "Your name",
        "-n",
        "--name",
        ValueTypes::RequiredSingle(Value::Str(String::new()))
    );
    
    // Set the callback
    app.set_callback(|data| {
        let name = data.get_option_value("name")
            .and_then(|v| v.as_str())
            .unwrap_or("World");
        
        let verbose = data.get_option_value("verbose").is_some();
        
        println!("Hello, {}!", name);
        if verbose {
            println!("Verbose mode enabled!");
        }
    });
    
    app.run();
}

Run it:

$ cargo run -- -n Alice -v

Hello, Alice!

Verbose mode enabled!

Core Concepts

Value Types

Fli provides explicit value types for type-safe option parsing:

use fli::{ValueTypes, Value};

// Flag option (no value)
ValueTypes::None

// Required single value
ValueTypes::RequiredSingle(Value::Str(String::new()))
ValueTypes::RequiredSingle(Value::Int(0))

// Optional single value with default
ValueTypes::OptionalSingle(Some(Value::Int(8080)))
ValueTypes::OptionalSingle(None)

// Required multiple values (at least 1)
ValueTypes::RequiredMultiple(vec![], None)

// Exactly N values required
ValueTypes::RequiredMultiple(vec![], Some(3))

// Optional multiple values
ValueTypes::OptionalMultiple(None, None)

// Up to N values
ValueTypes::OptionalMultiple(None, Some(5))

Commands and Subcommands

Create hierarchical command structures:

use fli::{Fli, ValueTypes, Value};

fn main() {
    let mut app = Fli::new("git", "2.0.0", "Version control system");
    
    // Create a command
    let commit_cmd = app.command("commit", "Record changes").unwrap();
    
    // Add options to the command
    commit_cmd.add_option(
        "message",
        "Commit message",
        "-m",
        "--message",
        ValueTypes::RequiredSingle(Value::Str(String::new()))
    );
    
    commit_cmd.add_option(
        "all",
        "Commit all changes",
        "-a",
        "--all",
        ValueTypes::None
    );
    
    // Set the command callback
    commit_cmd.set_callback(|data| {
        let message = data.get_option_value("message")
            .and_then(|v| v.as_str())
            .unwrap_or("No message");
        
        let all = data.get_option_value("all").is_some();
        
        println!("Committing with message: {}", message);
        if all {
            println!("Including all changes");
        }
    });
    
    app.run();
}

Accessing Values in Callbacks

The FliCallbackData provides convenient methods for accessing parsed values:

fn my_callback(data: &FliCallbackData) {
    // Get a single string value
    let name = data.get_option_value("name")
        .and_then(|v| v.as_str())
        .unwrap_or("default");
    
    // Get multiple string values
    let files = data.get_option_value("files")
        .and_then(|v| v.as_strings())
        .unwrap_or_default();
    
    // Check if a flag was passed
    let verbose = data.get_option_value("verbose").is_some();
    
    // Get positional arguments
    let first_arg = data.get_argument_at(0);
    let all_args = data.get_arguments();
    
    // Access the command
    let cmd_name = data.get_command().get_name();
}

Examples

Basic Calculator

use fli::{Fli, ValueTypes, Value};

fn main() {
    let mut app = Fli::new("calc", "1.0.0", "Simple calculator");
    
    let calc_cmd = app.command("calculate", "Perform calculation").unwrap();
    
    calc_cmd.add_option(
        "operation",
        "Operation to perform (add, sub, mul, div)",
        "-o",
        "--operation",
        ValueTypes::RequiredSingle(Value::Str(String::new()))
    );
    
    calc_cmd.set_expected_positional_args(2);
    
    calc_cmd.set_callback(|data| {
        let op = data.get_option_value("operation")
            .and_then(|v| v.as_str())
            .unwrap_or("add");
        
        let args = data.get_arguments();
        if args.len() < 2 {
            eprintln!("Error: Need two numbers");
            return;
        }
        
        let a: f64 = args[0].parse().unwrap_or(0.0);
        let b: f64 = args[1].parse().unwrap_or(0.0);
        
        let result = match op {
            "add" => a + b,
            "sub" => a - b,
            "mul" => a * b,
            "div" => a / b,
            _ => {
                eprintln!("Unknown operation: {}", op);
                return;
            }
        };
        
        println!("{} {} {} = {}", a, op, b, result);
    });
    
    app.run();
}

Usage:

$ calc calculate -o add 10 20

10 add 20 = 30

File Operations with Subcommands

use fli::{Fli, ValueTypes, Value};

fn main() {
    let mut app = Fli::new("file-tool", "1.0.0", "File operations");
    
    // File command with subcommands
    let file_cmd = app.command("file", "File operations").unwrap();
    
    // Copy subcommand
    file_cmd.subcommand("copy", "Copy files")
        .add_option(
            "source",
            "Source files",
            "-s",
            "--source",
            ValueTypes::RequiredMultiple(vec![], None)
        )
        .add_option(
            "dest",
            "Destination directory",
            "-d",
            "--dest",
            ValueTypes::RequiredSingle(Value::Str(String::new()))
        )
        .set_callback(|data| {
            let sources = data.get_option_value("source")
                .and_then(|v| v.as_strings())
                .unwrap_or_default();
            
            let dest = data.get_option_value("dest")
                .and_then(|v| v.as_str())
                .unwrap_or(".");
            
            println!("Copying {:?} to {}", sources, dest);
        });
    
    // Move subcommand
    file_cmd.subcommand("move", "Move files")
        .add_option(
            "path",
            "Files to move",
            "-p",
            "--path",
            ValueTypes::RequiredMultiple(vec![], None)
        )
        .set_callback(|data| {
            let paths = data.get_option_value("path")
                .and_then(|v| v.as_strings())
                .unwrap_or_default();
            
            println!("Moving: {:?}", paths);
        });
    
    app.run();
}

Usage:

$ file-tool file copy -s file1.txt file2.txt -d /backup

Copying ["file1.txt", "file2.txt"] to /backup


$ file-tool file move -p old1.txt old2.txt

Moving: ["old1.txt", "old2.txt"]

Greeting App with Options

use fli::{Fli, ValueTypes, Value};

fn main() {
    let mut app = Fli::new("greet", "1.0.0", "Greeting application");
    
    let greet_cmd = app.command("greet", "Greet someone").unwrap();
    
    greet_cmd.add_option(
        "name",
        "Name to greet",
        "-n",
        "--name",
        ValueTypes::RequiredSingle(Value::Str(String::new()))
    );
    
    greet_cmd.add_option(
        "time",
        "Time of day (morning, afternoon, evening)",
        "-t",
        "--time",
        ValueTypes::OptionalSingle(None)
    );
    
    greet_cmd.add_option(
        "repeat",
        "Number of times to repeat",
        "-r",
        "--repeat",
        ValueTypes::OptionalSingle(Some(Value::Int(1)))
    );
    
    greet_cmd.set_callback(|data| {
        let name = data.get_option_value("name")
            .and_then(|v| v.as_str())
            .unwrap_or("friend");
        
        let time = data.get_option_value("time")
            .and_then(|v| v.as_str())
            .unwrap_or("Hello");
        
        let greeting = match time {
            "morning" => "Good morning",
            "afternoon" => "Good afternoon",
            "evening" => "Good evening",
            _ => "Hello",
        };
        
        let repeat = data.get_option_value("repeat")
            .and_then(|v| match v {
                ValueTypes::OptionalSingle(Some(Value::Int(n))) => Some(*n),
                _ => None,
            })
            .unwrap_or(1);
        
        for _ in 0..repeat {
            println!("{}, {}!", greeting, name);
        }
    });
    
    app.run();
}

Usage:

$ greet greet -n Alice -t morning -r 2

Good morning, Alice!

Good morning, Alice!

Advanced Features

Custom Help Messages

Fli automatically generates beautiful help messages:

$ myapp --help

Command: myapp


A sample CLI application


Usage

  myapp [SUBCOMMANDS] [ARGUMENT] [ARGUMENT] [OPTIONS]

  [SUBCOMMANDS] [OPTIONS]  -- [ARGUMENT] [ARGUMENT]


Options

┌───────┬────────────┬──────────────────────┬─────────────────────┐

│ Flag  │ Long Form  │ Value Type           │ Description         │

├───────┼────────────┼──────────────────────┼─────────────────────┤

│ -v    │ --verbose  │ none                 │ Enable verbose      │

│ -n    │ --name     │ single (required)    │ Your name           │

└───────┴────────────┴──────────────────────┴─────────────────────┘

Debug Mode

Enable debug output to see internal parsing details:

let app = Fli::new("myapp", "1.0.0", "Description")
    .with_debug();

// Or add a debug flag
app.add_debug_option();

Error Handling

Commands return Result<&mut FliCommand> for better error handling:

use fli::Result;

fn main() -> Result<()> {
    let mut app = Fli::new("myapp", "1.0.0", "Description");
    
    let cmd = app.command("serve", "Start server")?;
    cmd.add_option(
        "port",
        "Port to bind",
        "-p",
        "--port",
        ValueTypes::RequiredSingle(Value::Int(8080))
    );
    
    app.run();
    Ok(())
}

Cargo.toml Integration

Initialize from your Cargo.toml metadata:

use fli::init_fli_from_toml;

fn main() {
    let mut app = init_fli_from_toml!();
    
    // App name, version, and description are automatically loaded
    // from your Cargo.toml file
    
    app.run();
}

Migration from 0.x

Version 1.0.0 includes significant improvements but breaks backwards compatibility. Key changes:

Option Syntax

Before (v0.x):

app.option("-n --name, <>", "Your name", callback);

After (v1.0):

app.add_option(
    "name",
    "Your name",
    "-n",
    "--name",
    ValueTypes::RequiredSingle(Value::Str(String::new()))
);
app.set_callback(callback);

Value Types

Callbacks

Before (v0.x):

fn callback(app: &Fli) {
    let name = app.get_values("name".to_owned()).unwrap()[0];
}

After (v1.0):

fn callback(data: &FliCallbackData) {
    let name = data.get_option_value("name")
        .and_then(|v| v.as_str())
        .unwrap_or("default");
}

Commands

Before (v0.x):

let cmd = app.command("serve", "Start server");

After (v1.0):

let cmd = app.command("serve", "Start server")?; // Returns Result

For a complete migration guide, see MIGRATION.md.

Documentation

• API Documentation
• Examples
• Changelog

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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

Acknowledgments

• Inspired by commander.js
• Built with ❤️ by Chibueze Aniezeofor (codad5)