zutils - User-Friendly Terminal Tools

A collection of user-friendly CLI tools written in Go that make common Linux tasks easier with beautiful, colored, and organized output.

Features

• 🎨 Beautiful colored terminal output - Easy to read and visually appealing
• 📊 Organized information display - Structured and logical layout
• 🚀 Fast and lightweight - Single binary, no external dependencies
• 🔍 Comprehensive information - Multiple data points in one view
• 💡 Token estimation - For AI/LLM context planning
• ⚡ Easy to use - Just one character shortcut: z
• 🏗️ Well-structured - Modular architecture for easy expansion

Installation

Build from source

cd zutils
go build -o zutils

Install to system path

# Using the install script (recommended)
./install.sh

# Or manually
cp zutils ~/.local/bin/
ln -s ~/.local/bin/zutils ~/.local/bin/z

The install script creates both zutils and z (shortcut) commands.

Usage

Command Syntax

z info <file|dir|network|path>

Or without the info subcommand (auto-detect):

z <file|directory>

Examples

File Information

Get detailed information about a file:

z info main.go
# or simply
z main.go

Output includes:

• File path and name
• File size (formatted)
• File type detection
• Content statistics:
  • Line count
  • Word count
  • Character count
  • Estimated token count (for AI/LLM context)
• File details:
  • Permissions (human-readable)
  • Last modified timestamp
  • File extension

Directory Information

Analyze a directory:

z info /path/to/directory
# or simply
z /path/to/directory

Output includes:

• Total directory size
• File count
• Directory count
• Largest files (top 5)
• Largest directories (top 5)
• File type distribution
• Last modified timestamp

Network Information

Display network information:

z info network

Output includes:

• Local IP addresses (IPv4 and IPv6)
• Public IP address
• DNS servers
• Active network connections (top 10)

Quick Reference

# File information
z README.md
z info file main.go

# Directory information
z .
z info dir /path/to/dir

# Network information
z info network

# Auto-detect (file or directory)
z /path/to/anything

Project Structure

The project follows a clean, modular architecture for easy expansion:

zutils/
├── cmd/                 # Command implementations
│   ├── info.go          # Info command router
│   ├── file.go          # File information
│   ├── dir.go           # Directory information
│   ├── network.go       # Network information
│   └── autodetect.go    # Auto-detection logic
├── pkg/                 # Shared packages
│   ├── colors/          # Color constants
│   ├── formatter/       # Output formatting utilities
│   └── types/           # Command registry and types
├── examples/            # Example files for testing
├── main.go             # Entry point
├── go.mod              # Go module definition
├── install.sh          # Installation script
└── README.md           # This file

Architecture Highlights

Command Registry Pattern:

• Easy to add new commands
• Centralized command management
• Extensible handler system

Modular Design:

• Separated concerns (commands, colors, formatting, types)
• Reusable components
• Easy to maintain and test

No External Dependencies:

• Uses Go standard library only
• Fast compilation
• Small binary size

Adding New Commands

The project is designed to make adding new commands easy:

1. Create a new file in cmd/ directory
2. Implement your command handler function
3. Register it in main.go using the command registry

Example:

// In cmd/mycommand.go
package cmd

import (
    "fmt"
    "github.com/zemenawi/zutils/pkg/colors"
)

func MyCommand(args []string) error {
    fmt.Printf("%s%sHello from my command!%s\n", colors.Green, colors.Bold, colors.Reset)
    return nil
}

// In main.go
registry.Register(&types.Command{
    Name:        "mycmd",
    Description: "My custom command",
    Handler:     cmd.MyCommand,
})

Why zutils?

Traditional Linux tools suffer from:

• ❌ Confusing command-line options and flags
• ❌ Unformatted or hard-to-read output
• ❌ Multiple tools needed for simple tasks
• ❌ Poor default displays that overwhelm users

zutils solves these issues by:

• ✅ Providing intuitive commands
• ✅ Beautiful, colored, organized output
• ✅ Combining multiple pieces of information in one view
• ✅ Great user experience for terminal users
• ✅ Single-character shortcut (z)
• ✅ Auto-detection of file/directory types

Token Estimation

The token count is estimated using a rough approximation (words / 0.75), commonly used for:

• Planning AI/LLM context windows
• Estimating API token costs
• Understanding text complexity

Note: Actual token counts vary by model and tokenizer. This is an estimate for planning purposes.

Development

Building

go build -o zutils

Cross-compilation

# Linux
GOOS=linux GOARCH=amd64 go build -o zutils-linux-amd64

# macOS
GOOS=darwin GOARCH=amd64 go build -o zutils-darwin-amd64

# Windows
GOOS=windows GOARCH=amd64 go build -o zutils-windows-amd64.exe

Testing

# Test file info
z info main.go

# Test directory info
z info .

# Test network info
z info network

# Test auto-detect
z main.go
z .

Future Enhancements

Planned features for future versions:

• stats command - System overview (CPU, RAM, Disk, processes)
• find command - File searching with filters
• diff command - Side-by-side file comparison
• compress / extract commands - Archive handling
• procs command - Process management
• port command - Port usage checking
• mem command - Memory usage details
• disk command - Disk usage analysis
• watch mode - Monitor changes in real-time
• JSON output mode for scripting
• Configuration file for custom colors
• Shell completion (bash, zsh, fish)

License

MIT License - Feel free to use, modify, and distribute.

Contributing

Contributions are welcome! The modular structure makes it easy to add new features:

1. Add your command to cmd/
2. Use shared utilities from pkg/
3. Register in main.go
4. Test thoroughly
5. Submit pull request

Feel free to:

• Report bugs
• Suggest new features
• Submit pull requests
• Improve documentation

Author

Created with ❤️ to make terminal tools more user-friendly.

---

Tip: Use z as your one-character shortcut for all zutils commands!