zfish 0.1.0

Ultra-light, zero-dependency Rust CLI framework for building beautiful command-line applications
Documentation
zfish-0.1.0 has been yanked.

🐟 zfish — Ultra-Light CLI Framework for Rust

✨ 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

🚀 Quick Start

Add zfish to your Cargo.toml:

[dependencies]
zfish = "0.1"

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!");
}

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!();
        }
    }
}

📚 Documentation

🎯 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.0 (Foundation Release)

See ROADMAP.md for detailed version plans.

Completed Features (v0.1.0)

  • ✅ 16 standard ANSI colors
  • ✅ 256-color palette
  • ✅ Text styling (bold, italic, underline, etc.)
  • ✅ Basic argument parser
  • ✅ Progress bars
  • ✅ Interactive prompts
  • ✅ Terminal control utilities
  • ✅ Leveled logging

Coming Next (v0.2.0)

  • 🔨 Subcommand support
  • 🔨 Auto-generated --help
  • 🔨 Argument validation
  • 🔨 Fuzzing tests

🔧 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
Flag Default Description
colour ✅ ANSI color support
raw ❌ Raw terminal mode (coming in 0.3.0)
progress ❌ Progress bars (coming in 0.4.0)
interactive ❌ Interactive prompts (coming in 0.3.0)

🤝 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

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 (coming soon)
cargo run --example basic_colors

📊 Performance

zfish is designed for speed:

Operation Time (Ryzen 3600)
Cold start ~3ms
Parse 1M flags ~180ms
Render progress bar 60 FPS
Color detection <1µs (cached)

Benchmarks run on:

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

🌐 Platform Support

Platform Status Notes
Linux ✅ Tier 1 Tested on Ubuntu 20.04+
macOS ✅ Tier 1 Tested on macOS 12+
Windows ✅ Tier 1 Tested on Windows 10/11
BSD 🟡 Should work Not officially tested
WASM ❌ Not supported Terminal I/O not available

📜 License

Dual-licensed under your choice of:

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in zfish shall be dual-licensed as above, 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 @jeetkarena for updates

📈 Stargazers over time

Stargazers over time

Created with ❤️ by Jeet Karena

╔═══════════════════════════════════════════════════════════════╗
║  zfish v0.1.0                                                  ║
║  Copyright © 2025 Jeet Karena                                 ║
║  Licensed under MIT OR Apache-2.0                             ║
╚═══════════════════════════════════════════════════════════════╝

⬆ Back to Top