https://github.com/onurhan1337/quzz-cli
Browse and analyze Quzz traces from your terminal. Filter by component, duration, and errors, and toggle a stats view.
https://github.com/onurhan1337/quzz-cli
bubbles bubbletea cobra go goreleaser
Last synced: about 1 month ago
JSON representation
Browse and analyze Quzz traces from your terminal. Filter by component, duration, and errors, and toggle a stats view.
- Host: GitHub
- URL: https://github.com/onurhan1337/quzz-cli
- Owner: onurhan1337
- License: mit
- Created: 2025-10-29T22:35:19.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2025-10-30T16:07:58.000Z (8 months ago)
- Last Synced: 2025-10-30T18:07:47.405Z (8 months ago)
- Topics: bubbles, bubbletea, cobra, go, goreleaser
- Language: Go
- Homepage:
- Size: 53.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://github.com/onurhan1337/quzz-cli/releases).
**macOS/Linux:**
```bash
# 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](https://github.com/onurhan1337/quzz-cli/releases)
2. Extract `quzz.exe`
3. Add to your PATH or move to a directory in your PATH
### Option 2: Install with Go
```bash
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:
```bash
quzz init
```
Visualize traces:
```bash
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.
```bash
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.
```bash
quzz visualize traces.json
```
**Filtering:**
```bash
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`):
```javascript
module.exports = {
logLevel: "info",
outputFormat: "pretty",
performance: {
enabled: true,
warnThreshold: 500,
},
componentFilter: /^(Blog|Product)/,
};
```
## Technologies
- [Bubble Tea](https://github.com/charmbracelet/bubbletea) - TUI framework
- [Bubbles](https://github.com/charmbracelet/bubbles) - TUI components
- [Lipgloss](https://github.com/charmbracelet/lipgloss) - Terminal styling
- [Cobra](https://github.com/spf13/cobra) - CLI framework
## Development
```bash
go build -o quzz
go test ./...
```
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Links
- [Quzz npm package](https://github.com/onurhan1337/quzz)
- [Report Issues](https://github.com/onurhan1337/quzz-cli/issues)