{"id":27253563,"url":"https://github.com/miklosn/cmdperf","last_synced_at":"2025-10-26T16:34:28.634Z","repository":{"id":285624528,"uuid":"957646748","full_name":"miklosn/cmdperf","owner":"miklosn","description":"Command Performance Benchmarking","archived":false,"fork":false,"pushed_at":"2025-04-08T06:34:42.000Z","size":202,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-11T01:55:21.928Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/miklosn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-30T21:25:10.000Z","updated_at":"2025-04-07T20:27:19.000Z","dependencies_parsed_at":"2025-04-01T19:46:18.503Z","dependency_job_id":"51fc0608-f501-4f33-ab20-8a1b61ba5bcc","html_url":"https://github.com/miklosn/cmdperf","commit_stats":null,"previous_names":["miklosn/cmdperf"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miklosn%2Fcmdperf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miklosn%2Fcmdperf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miklosn%2Fcmdperf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miklosn%2Fcmdperf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/miklosn","download_url":"https://codeload.github.com/miklosn/cmdperf/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248328109,"owners_count":21085258,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-11T01:55:25.473Z","updated_at":"2025-10-26T16:34:28.626Z","avatar_url":"https://github.com/miklosn.png","language":"Go","funding_links":[],"categories":["Development"],"sub_categories":["Testing"],"readme":"# ✨ cmdperf - Interactive Command Performance Benchmarking ✨\n\n`cmdperf` is a terminal tool designed for developers who need to quickly **measure, compare, and understand the performance characteristics of shell commands**. Whether you're evaluating different implementations of a task (e.g., `grep` vs `rg`), checking the impact of command-line flags, or getting a feel for command latency under specific conditions (like concurrency or rate limits), `cmdperf` provides interactive feedback and clear, comparable results right in your terminal.\n\n![cmdperf demo](doc/demo.gif)\n\n## Features\n\n- Benchmark shell commands\n- Support for parallel execution\n- Compare commands\n- Real-time terminal UI with live statistics, progress tracking and ETA\n- Responsive\n- Color schemes :)\n\n## Non-Goals\n\n- Precise analysis. We're deliberately spawning shells and such. cmdperf is a tool for quick and dirty benchmarking, not a scientific tool.\n- Not a replacement for specialized benchmarking tools.\n\n## Why Choose `cmdperf`?\n\nWhile various tools exist, `cmdperf` offers a unique blend of features particularly useful for developers during analysis and comparison:\n\n- **Interactive Real-time UI:** Unlike tools that only output results at the end, `cmdperf` provides a live-updating terminal interface showing progress, statistics (mean, min/max, stddev), and ETA. This visual feedback helps you understand performance *during* execution.\n- **Direct Command Comparison:** Easily benchmark multiple commands head-to-head in a single invocation, with results clearly presented for comparison.\n- **Concurrency Testing:** Run multiple instances of a command concurrently (`-c` flag) to understand performance under parallel load.\n- **Rate Limiting:** Simulate specific throughput scenarios (`--rate` flag) to test how commands or the systems they interact with perform under controlled request rates.\n- **Shell Flexibility:** Run commands via a specified shell (handling pipes, redirection, etc.) or execute them directly (`-N` flag) for simpler cases, avoiding shell overhead.\n- **Multiple Output Formats:** Besides the TUI, results can be easily exported to Markdown (`--markdown`) or CSV (`--csv`) for documentation or further analysis.\n- **Designed for Quick Insights:** While acknowledging it's not for rigorous scientific benchmarking (see Non-Goals), it's optimized for developers needing fast, actionable performance feedback.\n\n`cmdperf` is ideal when you need more than basic timing but want an easier, more interactive experience than complex profiling suites, especially when comparing command variations or simulating specific load conditions.\n\n## Installation\n\nThere are several ways to install `cmdperf`:\n\n### Using `go install`\n\nIf you have a Go development environment set up, you can install the latest development version directly using `go install`:\n\n```bash\ngo install github.com/miklosn/cmdperf/cmd/cmdperf@latest\n```\n\nEnsure your `GOPATH/bin` or `GOBIN` directory is included in your system's `PATH`.\n\n### Using Homebrew (macOS/Linux)\n\nOn macOS or Linux, you can install `cmdperf` using Homebrew:\n\n```bash\nbrew install miklosn/tap/cmdperf\n```\n\n### Using Pre-built Binaries\n\nPre-compiled binaries are available for Linux, macOS, and Windows on the [GitHub Releases page](https://github.com/miklosn/cmdperf/releases).\n\n1. Download the appropriate archive for your operating system and architecture (e.g., `cmdperf_Linux_x86_64`, `cmdperf_Darwin_arm64`, `cmdperf_Windows_x86_64.exe`).\n2. Extract the binary from the archive (if necessary).\n3. (Linux/macOS) Make the binary executable: `chmod +x cmdperf_*`\n4. Move the binary to a directory included in your system's `PATH`. Common locations include `/usr/local/bin` or `~/bin` on Linux/macOS. For Windows, you can place it in a directory and add that directory to your `PATH` environment variable.\n\n### Using Package Managers (Linux)\n\n`.deb` and `.rpm` packages are also provided on the [GitHub Releases page](https://github.com/miklosn/cmdperf/releases) for easier installation on compatible Linux distributions.\n\n**Debian/Ubuntu:**\n\nDownload the `.deb` package and install it using `dpkg`:\n\n```bash\nsudo dpkg -i cmdperf_*.deb\n```\n\nIf you encounter dependency issues, run:\n\n```bash\nsudo apt --fix-broken install\n```\n\n**Fedora/CentOS/RHEL:**\n\nDownload the `.rpm` package and install it using `rpm` or `dnf`:\n\n```bash\n# Using rpm\nsudo rpm -i cmdperf_*.rpm\n\n# Or using dnf\nsudo dnf install cmdperf_*.rpm\n```\n\n## Usage\n\n```bash\ncmdperf [options] \u003ccommand...\u003e\n```\n\nFor example:\n\n```bash\n# Basic usage\ncmdperf \"sleep 0.1\"\n\n# Multiple commands to compare\ncmdperf \"grep 'ERROR' mock.log\" \"rg 'ERROR' mock.log\"\n\n# Parallel execution with 10 concurrent processes\ncmdperf -c 10 \"curl -s https://example.com \u003e /dev/null\"\n\n# Run 100 iterations of each command\ncmdperf -n 100 \"redis-cli PING\"\n\n# Run benchmark for 30 seconds\ncmdperf -d 30s \"redis-cli PING\"\n\n# Output results to a Markdown file\ncmdperf --markdown results.md \"sleep 0.1\" \"sleep 0.2\"\n\n# Output results to a CSV file\ncmdperf --csv results.csv \"sleep 0.1\" \"sleep 0.2\"\n```\n\n## CLI Options\n\n```\nArguments:\n  \u003ccommand...\u003e    Command(s) to benchmark\n\nOptions:\n  -n, --runs=\u003cn\u003e                Number of runs to perform [default: 10]\n  -c, --concurrency=\u003cn\u003e         Number of concurrent executions [default: 1]\n      --color-scheme=\u003cscheme\u003e   Color scheme to use (auto, catppuccin, tokyonight, nord, monokai, solarized, solarized-light, gruvbox, monochrome) [default: auto]\n      --list-color-schemes      List available color schemes\n  -t, --timeout=\u003cduration\u003e      Timeout for each command execution [default: 1m]\n  -d, --duration=\u003cduration\u003e     Total benchmark duration (overrides --runs)\n  -r, --rate=\u003crate\u003e            Target rate limit (requests per second)\n  -s, --shell=\u003cshell\u003e           Shell to use for command execution [default: /bin/sh]\n      --shell-opt=\u003copt\u003e         Shell option (can be repeated) [default: -c]\n  -N, --no-shell                Execute commands directly without a shell\n      --csv=\u003cfile\u003e              Write results to CSV file\n      --markdown=\u003cfile\u003e         Write results to Markdown file\n      --version                 Show version information\n      --fail-on-error           Exit with non-zero status if any command returns non-zero exit code\n      --cpu-profile=\u003cfile\u003e      Write CPU profile to file\n      --mem-profile=\u003cfile\u003e      Write memory profile to file\n      --block-profile=\u003cfile\u003e    Write goroutine blocking profile to file\n      --pprof-server            Start pprof HTTP server on :6060\n```\n\n## Color Schemes\n\ncmdperf supports various color schemes to match your terminal theme:\n\n```bash\n# Use a specific color scheme\ncmdperf --color-scheme=nord \"sleep 0.1\"\n\n# Automatically detect terminal background and choose appropriate theme\ncmdperf --color-scheme=auto \"sleep 0.1\"\n\n# List available color schemes\ncmdperf --list-color-schemes\n```\n\nAvailable color schemes include:\n\n- default: Default color scheme\n- auto: Automatically selects a theme based on terminal background\n- catppuccin: Soothing pastel theme (Mocha variant)\n- tokyonight: A dark and elegant theme\n- nord: Arctic, north-bluish color palette\n- monokai: Vibrant and colorful theme\n- solarized: Precision colors for machines and people (dark variant)\n- solarized-light: Precision colors for machines and people (light variant)\n- monochrome: Simple black and white theme (no colors)\n\n## Direct Execution Mode\n\nBy default, cmdperf executes commands through a shell (usually `/bin/sh -c`). This allows for shell features like pipes, redirections, and variable expansions. However, for simple commands, you can use direct execution mode to bypass the shell:\n\n```bash\ncmdperf -N \"ls -la\"\n```\n\nIn direct execution mode:\n\n- The command is split by spaces (respecting quotes)\n- The first part is used as the executable\n- The remaining parts are passed as arguments\n- Shell features like pipes (`|`), redirections (`\u003e`), and variable expansions (`$VAR`) won't work\n- The command is executed directly without a shell\n\nPlease note that even without spawning a shell, `cmdperf` is not designed for high frequency benchmarking.\n\n## Output\n\ncmdperf provides a colorful, real-time UI that shows:\n\n- Command execution progress\n- Mean execution time with standard deviation\n- Min/max execution time range\n- Estimated time to completion\n- Comparison between commands (when benchmarking multiple commands)\n\n## CSV Output\n\nYou can export benchmark results to a CSV file for further analysis:\n\n```bash\ncmdperf --csv=results.csv \"sleep 0.1\" \"sleep 0.2\"\n```\n\nThe CSV output includes detailed metrics for each command:\n\n- Command string\n- Total runs and successful runs\n- Error counts and non-zero exit codes\n- Timing statistics (min, max, mean, median, standard deviation)\n- Throughput and target rate (if rate limiting was used)\n\n## Markdown Output\n\nYou can export benchmark results to a Markdown file for documentation or sharing:\n\n```bash\ncmdperf --markdown=results.md \"sleep 0.1\" \"sleep 0.2\"\n```\n\n## Rate Limiting\n\nYou can limit the rate at which commands are executed using the `--rate` option:\n\n```bash\n# Limit execution to 10 requests per second\ncmdperf --rate=10 \"redis-cli GET mykey\"\n```\n\nThis is useful for:\n\n- Simulating specific load patterns\n- Preventing overloading of the target system\n- Testing how services perform under controlled request rates\n\nThe actual achieved rate will be reported in the results, allowing you to compare the target rate with what was actually achieved.\n\n## Community \u0026 Support\n\nFound `cmdperf` useful? Here's how you can get involved or get help:\n\n- **⭐ Star the Project:** Show your support by starring the [cmdperf repository](https://github.com/miklosn/cmdperf) on GitHub!\n- **🐞 Report Issues:** Encounter a bug or have a suggestion? Please open an issue on the [GitHub Issues page](https://github.com/miklosn/cmdperf/issues).\n- **🤝 Contribute:** We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on how to submit pull requests, report bugs, or suggest features.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmiklosn%2Fcmdperf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmiklosn%2Fcmdperf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmiklosn%2Fcmdperf/lists"}