Quzz CLI

A powerful CLI for debugging React Server Components. Built with Go and Bubble Tea for a modern, interactive terminal experience.

Features

• Interactive TUI - Full-screen terminal interface with smooth navigation
• Keyboard Shortcuts - Vim-style (j/k) and arrow keys
• Smart Pagination - Handles large trace files efficiently
• Rich Filtering - By component, duration, date, errors, and more
• Statistics Dashboard - Toggle detailed stats with Tab key
• Zero-Config - Works out of the box

Installation

Option 1: Download Pre-built Binaries (Recommended)

Download the latest release for your platform from GitHub Releases.

macOS/Linux:

# Download, extract, and install (replace VERSION and OS/ARCH as needed)
curl -LO https://github.com/onurhan1337/quzz-cli/releases/download/v1.0.0/quzz-cli_Darwin_x86_64.tar.gz
tar -xzf quzz-cli_Darwin_x86_64.tar.gz
sudo mv quzz /usr/local/bin/
quzz --version

Windows:

1. Download the .zip file from Releases
2. Extract quzz.exe
3. Add to your PATH or move to a directory in your PATH

Option 2: Install with Go

go install github.com/onurhan1337/quzz-cli@latest

Note: The binary will be named quzz-cli when using go install. Run commands as quzz-cli instead of quzz.

Quick Start

Initialize configuration:

quzz init

Visualize traces:

quzz visualize traces.json

Keyboard Shortcuts

Key	Action
Up / k	Scroll up
Down / j	Scroll down
PgUp / b	Page up
PgDn / f	Page down
Home / g	Jump to top
End / G	Jump to bottom
Tab	Toggle statistics
?	Show help
q / Esc	Quit

Commands

quzz init

Interactive setup wizard for project configuration.

quzz init                 # Interactive mode
quzz init --typescript    # Generate TypeScript config
quzz init --skip-prompts  # Use defaults

quzz visualize [path]

View and analyze traces with interactive TUI.

quzz visualize traces.json

Filtering:

quzz visualize traces.json --component UserProfile
quzz visualize traces.json --min-duration 100 --max-duration 500
quzz visualize traces.json --errors
quzz visualize traces.json --component-regex "^(Blog|Product)"

Flags:

• -c, --component - Filter by component name
• -o, --operation - Filter by operation
• -l, --level - Filter by log level (error, warn, info, debug)
• --min-duration - Minimum duration in ms
• --max-duration - Maximum duration in ms
• --errors - Show only errors
• --warnings - Show only warnings
• --component-regex - Filter by regex pattern
• --limit - Limit number of traces (default: 50)
• -j, --json - Output as JSON
• -s, --stats - Show only statistics

Configuration

Generated config file (quzz.config.js or quzz.config.ts):

module.exports = {
  logLevel: "info",
  outputFormat: "pretty",
  performance: {
    enabled: true,
    warnThreshold: 500,
  },
  componentFilter: /^(Blog|Product)/,
};

Technologies

• Bubble Tea - TUI framework
• Bubbles - TUI components
• Lipgloss - Terminal styling
• Cobra - CLI framework

Development

go build -o quzz
go test ./...

License

MIT License - see LICENSE file for details.

Links

• Quzz npm package
• Report Issues