🐟 zfish — Ultra-Light CLI Framework for Rust

Soar above the complexity

📋 View the full roadmap and feature status on Notion →

✨ Features

• 🚀 Zero Dependencies — No third-party crates, only std
• 🎨 Rich Styling — 16 ANSI colors + 256-color palette
• ⚡ Blazing Fast — Cold start <5ms, parse 1M flags in ~200ms
• 🔒 Memory Safe — #![forbid(unsafe_code)] in public API
• 🌍 Cross-Platform — Linux, macOS, Windows (tier-1 support)
• 📦 Lightweight — Minimal binary size, fast compile times
• 🎯 Intuitive API — Ergonomic design, great docs
• 🔮 Edition 2024 — Built with the latest Rust features

🎁 What's Included

📖 See the Feature Matrix below for detailed capabilities

🚀 Quick Start

Installation

Add zfish to your Cargo.toml:

[dependencies]
zfish = "0.1.10"

Alternative: Install from GitHub Packages

Download the .crate file from GitHub Releases:

# Download the latest release
wget https://github.com/JeetKarena/ZFish/releases/download/v0.1.10/zfish-0.1.10.crate

# Verify checksum (optional)
wget https://github.com/JeetKarena/ZFish/releases/download/v0.1.10/zfish-0.1.10.crate.sha256
sha256sum -c zfish-0.1.10.crate.sha256

# Install from local crate
cargo install --path zfish-0.1.10.crate

Hello, Colorful World!

use zfish::Color;

fn main() {
    println!("{}", Color::Green.paint("✓ Success!"));
    println!("{}", Color::Red.paint("✗ Error!"));
    println!("{}", Color::Yellow.paint("⚠ Warning!"));
}

Argument Parsing

use zfish::Args;

fn main() {
    let args = Args::parse();
    
    if args.has_flag("verbose") || args.has_flag("v") {
        println!("Verbose mode enabled");
    }
    
    if let Some(file) = args.get_option("file") {
        println!("Processing: {}", file);
    }
    
    for arg in &args.positional {
        println!("Positional argument: {}", arg);
    }
}

Progress Bar

use zfish::ProgressBar;
use std::thread;
use std::time::Duration;

fn main() {
    let mut pb = ProgressBar::new(100);
    
    for i in 0..=100 {
        pb.set(i);
        thread::sleep(Duration::from_millis(50));
    }
    
    pb.finish("✓ Complete!");
}

Subcommands (Git-Style CLI)

use zfish::command::{App, Command, Arg};

fn main() {
    let app = App::new("myapp")
        .version("1.0.0")
        .about("My awesome CLI")
        .arg(Arg::new("verbose").short('v').long("verbose"))
        .subcommand(
            Command::new("init")
                .about("Initialize a new project")
                .arg(Arg::new("name").required(true))
        )
        .subcommand(
            Command::new("build")
                .about("Build the project")
                .arg(Arg::new("release").long("release"))
        );

    let matches = app.get_matches();
    
    match matches.subcommand() {
        Some(("init", sub_matches)) => {
            let name = sub_matches.value_of("name").unwrap();
            println!("Initializing: {}", name);
        }
        Some(("build", sub_matches)) => {
            if sub_matches.is_present("release") {
                println!("Building in release mode");
            }
        }
        _ => println!("Use --help for usage"),
    }
}

Interactive Prompts

use zfish::Prompt;

fn main() {
    let name = Prompt::text("What's your name?");
    println!("Hello, {}!", name);
    
    if Prompt::confirm("Continue?") {
        println!("Let's go!");
    }
    
    let password = Prompt::password("Enter password:");
    println!("Password length: {}", password.len());
}

256-Color Palette

use zfish::Color;

fn main() {
    // Use any color from 0-255
    println!("{}", Color::Custom(196).paint("Bright red"));
    println!("{}", Color::Custom(46).paint("Bright green"));
    println!("{}", Color::Custom(21).paint("Deep blue"));
    
    // Show all 256 colors
    for i in 0..=255 {
        print!("{} ", Color::Custom(i).paint(format!("{:3}", i)));
        if (i + 1) % 16 == 0 {
            println!();
        }
    }
}

Beautiful Tables

use zfish::table::{Table, BoxStyle, Alignment};
use zfish::Color;

fn main() {
    let mut table = Table::new(vec!["Name", "Language", "Stars"]);
    table.set_box_style(BoxStyle::Rounded);
    table.set_column_alignment(2, Alignment::Right);
    
    table.add_row(vec!["zfish", "Rust", "⭐⭐⭐⭐⭐"]);
    table.add_row(vec!["clap", "Rust", "⭐⭐⭐⭐"]);
    table.add_row(vec!["cobra", "Go", "⭐⭐⭐"]);
    
    table.print();
    // Output:
    // ╭──────────┬──────────┬───────╮
    // │ Name     │ Language │ Stars │
    // ├──────────┼──────────┼───────┤
    // │ zfish    │ Rust     │ ⭐⭐⭐⭐⭐ │
    // │ clap     │ Rust     │ ⭐⭐⭐⭐ │
    // │ cobra    │ Go       │ ⭐⭐⭐ │
    // ╰──────────┴──────────┴───────╯
}

📚 Documentation

• Developer Docs: zfish-devdocs.vercel.app — Interactive guides and tutorials
• API Docs: docs.rs/zfish — Generated Rust documentation
• Roadmap: ROADMAP.md — Detailed feature roadmap
• Public Roadmap: Notion Roadmap — Live feature status & timeline
• Installation Guide: PACKAGES.md — Multiple installation methods
• Release Process: .github/RELEASE_PROCESS.md — How we create releases
• Examples: examples/ — 18 comprehensive examples covering all features
  • 01_hello_world.rs — Basic usage
  • 02_argument_parsing.rs — CLI argument handling
  • 03_colored_text.rs — 16 + 256 color palette
  • 04_progress_bar.rs — 4 progress bar styles
  • 05_logger.rs — Leveled logging
  • 06_terminal_control.rs — Terminal manipulation
  • 07_interactive_prompts.rs — User input
  • 08_complete_cli.rs — Full-featured CLI app
  • 09_subcommands.rs — Nested command structures
  • 10_arg_features_v2.rs — Advanced argument features
  • 11_core_features_demo.rs — Core functionality showcase
  • 12_beautiful_reports.rs — Styled report generation
  • 13_table_examples.rs — 12 automated table examples with all box styles
  • 14_alignment_test.rs — Table emoji alignment verification
  • 15_debug_emoji_width.rs — Unicode width debugging
  • 16_comprehensive_unicode_test.rs — Full Unicode support test
  • 17_unicode_edge_cases.rs — Complex emoji sequences
  • 18_manual_table_drawing.rs — Manual table fallback for custom layouts

🎯 Design Philosophy

Why zfish?

Most CLI frameworks pull in dozens of dependencies, increasing:

• Compile times (minutes instead of seconds)
• Binary size (MBs instead of KBs)
• Supply chain risk (trust dozens of crates)
• Maintenance burden (breaking changes cascade)

zfish takes a different approach:

┌─────────────────────────────────────────────────────┐
│  Other CLI Frameworks       │  zfish                 │
├─────────────────────────────────────────────────────┤
│  50+ dependencies           │  0 dependencies       │
│  ~10 second compile         │  ~1 second compile    │
│  ~2 MB binary               │  ~200 KB binary       │
│  Complex API                │  Intuitive API        │
│  ANSI escape codes manual   │  Auto color detection │
└─────────────────────────────────────────────────────┘

Core Principles

1. Zero Dependencies — Only Rust std library
2. Safety First — No unsafe code in public API
3. Performance — Optimized for speed and size
4. Simplicity — Easy to learn, hard to misuse
5. Cross-Platform — Works everywhere Rust works

🚀 Project Status

Current Version: 0.1.10 (Active Development)

📋 For detailed feature status, implementation notes, and roadmap, visit our Notion Roadmap →

See ROADMAP.md for version plans.

📊 Feature Matrix

Legend: ✅ Implemented | 🔨 In Progress | 🟡 Partial/Untested | ❌ Not Available

Completed Features (v0.1.x - v0.2.x)

Core Styling & Colors

• ✅ 16 standard ANSI colors
• ✅ 256-color palette (0-255)
• ✅ Text styling (bold, italic, underline, dim, blink, reverse, hidden, strikethrough)

Argument Parsing & Commands

• ✅ Basic argument parser (flags, options, positional args)
• ✅ Subcommand system (git-style, multi-level hierarchies)
• ✅ Auto-generated --help text for all commands
• ✅ Argument validation (required args, possible values, custom validators)
• ✅ Advanced arg features (environment variable fallbacks, delimiters, dependencies, conflicts)
• ✅ Variadic arguments (capture multiple values)

Progress & Interactive

• ✅ 4 progress bar styles (bar, spinner, dots, arrows)
• ✅ Interactive prompts (text, confirm, password)

Terminal Control

• ✅ Terminal control (clear screen, cursor movement)
• ✅ Terminal size detection (Windows + Unix)

Logging & Tables

• ✅ Leveled logging (error, warn, info, debug, trace)
• ✅ Table module with 5 box styles (Single, Double, Heavy, Rounded, ASCII)
• ✅ Unicode-aware width calculation (emojis, CJK, combining marks)
• ✅ Manual table drawing fallback for custom layouts
• ✅ Column alignment (Left, Right, Center)

Development & Examples

• ✅ Feature flags (colour, raw, progress, interactive)
• ✅ Edition 2024 support
• ✅ 18 comprehensive examples

Coming Next (v0.3.0+)

• 🔨 Multi-select prompts (checkbox lists)
• 🔨 Fuzzing tests for argument parser
• 🔨 Shell completion generation (bash, zsh, fish)
• 🔨 Configuration file support (TOML, JSON)
• 🔨 Spinner widgets with custom animations

💡 Want more details? Check our Interactive Roadmap on Notion for:

• Detailed implementation notes for each feature
• Release timelines and version planning
• Known issues and workarounds
• Feature request voting and discussions

🔧 Feature Flags

zfish uses Cargo feature flags for optional functionality:

[dependencies.zfish]
version = "0.1"
default-features = false  # Disable all defaults
features = ["colour"]     # Enable only what you need

Note: progress and interactive features require raw mode and are automatically enabled when you use them.

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Report Bugs — Open an issue with details
2. Request Features — Discuss in GitHub Discussions
3. Submit PRs — Check open issues labeled "good first issue"
4. Improve Docs — Fix typos, add examples

Documentation

• API Documentation — Complete API reference on docs.rs
• Developer Docs — Interactive guides, examples, and tutorials
• Roadmap — Feature status and upcoming releases

Development Setup

# Clone the repository
git clone https://github.com/JeetKarena/ZFish.git
cd zfish

# Run tests
cargo test

# Run tests (single-threaded to avoid env var conflicts)
cargo test -- --test-threads=1

# Build documentation
cargo doc --open

# Run examples
cargo run --example 01_hello_world
cargo run --example 02_argument_parsing
cargo run --example 03_colored_text
cargo run --example 04_progress_bar
cargo run --example 05_logger
cargo run --example 06_terminal_control
cargo run --example 07_interactive_prompts
cargo run --example 08_complete_cli

📊 Performance

zfish is designed for speed:

Benchmarks run on:

• CPU: AMD Ryzen 5 3600
• RAM: 16GB DDR4-3200
• OS: Windows 11 / Ubuntu 22.04

🌐 Platform Support

📜 License

Licensed under the MIT License.

See LICENSE for details or visit http://opensource.org/licenses/MIT.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in zfish shall be licensed under the MIT License, without any additional terms or conditions.

🙏 Acknowledgments

Inspired by:

• clap — Excellent API design patterns
• colored — Color API inspiration
• indicatif — Progress bar concepts
• dialoguer — Interactive prompt ideas

Built with zero dependencies as a proof-of-concept that powerful CLIs don't need to pull in half of crates.io.

💬 Community

• GitHub Discussions — Ask questions, share ideas
• Issues — Report bugs, request features
• Twitter — Follow @user_0xJeet for updates

📈 Stargazers over time

╔═══════════════════════════════════════════════════════════════╗
║  zfish v0.1.10                                                ║
║  Copyright © 2025 Jeet Karena                                 ║
║  Licensed under MIT License                                   ║
╚═══════════════════════════════════════════════════════════════╝