cmdrun

English | 日本語 | 简体中文 | 繁體中文

A fast, secure, cross-platform command runner

Register your commands once, run them from anywhere.

Table of Contents

• Why cmdrun?
• Installation
• Basic Usage
• Features
• Configuration Examples
• Documentation
• License

Why cmdrun?

🚀 Performance

• ~17x faster startup than Node.js-based task runners
• 6.5ms startup time (average) vs 115ms+ for npm/yarn
• 4.5MB memory footprint vs 200MB+ for Node.js

🔒 Security

• Zero Rust eval() - No dynamic code generation in application code
• Safe variable expansion - No shell injection vulnerabilities
• Fine-grained control - Hierarchical permission system for command chaining and subshells
  • allow_command_chaining - Control &&, ||, ; operators (default: disabled)
  • allow_subshells - Control () parentheses for regex patterns (default: disabled)
• Escape sequences - Support for \n, \r, \t with minimal security risk
• Dependency audit - Built-in security scanning

🔐 Security Report: See Security Documentation for threat model and audit results.

🌍 Cross-platform

• Supported OS: Linux, macOS, Windows, FreeBSD
• Shell detection: Auto-detects bash/zsh/fish/pwsh
• Native binaries: No runtime dependencies

💎 Developer Experience

• TOML configuration - Type-safe, easy to read
• Powerful features - Dependencies, parallel execution, hooks, Watch Mode
• Great errors - Detailed error messages with context

🎯 What Makes cmdrun Special

Unique combination of features:

• 🔒 Zero Rust eval() with fuzzing (373,423 tests, 0 crashes)
• 🌍 4-language support (EN/JA/ZH-CN/ZH-TW)
• 🎨 Shell completion (Zsh/Bash/Fish)
• 📊 SQLite-based execution history
• 🔌 Dynamic plugin system
• 🎯 Intelligent typo detection

Installation

System Requirements

• Operating System: Linux, macOS, Windows, FreeBSD
• Rust: 1.75+ (MSRV)

Install Rust Toolchain

# 1. Download and run Rustup (Rust installer)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 2. Load environment variables
source ~/.cargo/env

# 3. Verify installation
rustc --version
cargo --version

Build and Install cmdrun

# 1. Clone the repository
git clone git@github.com:sanae-abe/cmdrun.git
cd cmdrun

# 2. Build and install
cargo install --path .

# 3. Verify installation
cmdrun --version
cmdrun --help

Update

# If installed from source
cd cmdrun  # Navigate to project directory
git pull

# Rebuild and install
cargo install --path . --force

Uninstall

# 1. Remove binary
cargo uninstall cmdrun

# 2. Remove configuration files (optional)
# Linux/macOS
rm -rf ~/.config/cmdrun

# Windows (run in PowerShell)
# Remove-Item -Recurse -Force "$env:APPDATA\cmdrun"

# 3. Remove project directory (optional)
# cd ..
# rm -rf cmdrun

Note:

• cargo uninstall cmdrun only removes the executable
• Configuration files (commands.toml, etc.) need to be removed manually
• Skip step 2 if you want to keep your settings

Basic Usage

cmdrun is a fast, secure, cross-platform command runner that allows you to register and run frequently used commands from anywhere on your system.

Register your frequently used commands

# Add a command interactively
cmdrun add

# Or add directly with parameters
cmdrun add dev "npm run dev" "Start development server"
cmdrun add push "git add . && git commit && git push" "Commit and push changes"
cmdrun add prod-ssh "ssh user@production-server.com" "Connect to production server"
cmdrun add docker-clean "docker system prune -af" "Clean up unused Docker resources"
cmdrun add db-backup "pg_dump mydb > backup_$(date +%Y%m%d).sql" "Backup database"

Run and manage your commands

# Run a registered command
cmdrun run dev

# List all registered commands
cmdrun list

# Search for commands
cmdrun search docker

# Remove a command
cmdrun remove dev

Configuration management

# Show all settings
cmdrun config show

# Change language
cmdrun config set language japanese

# Use custom configuration file
cmdrun --config ~/work/commands.toml list
cmdrun -c ~/.cmdrun/personal.toml run dev

# Use only global configuration (skip local config)
cmdrun --global list
cmdrun -G run weather

# Show help
cmdrun --help

Configuration file location:

• Linux/macOS: ~/.config/cmdrun/commands.toml
• Windows: %APPDATA%\cmdrun\commands.toml
• Custom path: Use --config/-c option to specify any path
• Global only: Use --global/-G flag to skip local configuration and use only global settings

Features

cmdrun provides powerful features for command management and execution:

• Variable Expansion - ${VAR}, ${VAR:-default}, positional arguments ${1}, ${2}
• Dependencies - Run commands in sequence with deps = ["build"]
• Parallel Execution - Execute multiple commands simultaneously
• Platform-specific Commands - Different commands for Unix/Windows/Linux
• Hooks - Pre/post execution hooks for custom workflows
• Environment Management - Switch between dev/staging/prod environments
• History & Logging - Track command execution history and statistics
• Template System - Built-in templates for Rust/Node.js/Python/React projects
• Plugin System - Extend functionality with external plugins
• Watch Mode - Auto-run commands on file changes with glob patterns
• Shell Completion - Smart completion for Zsh/Bash/Fish with descriptions
• Typo Detection - Auto-detect and suggest corrections for mistyped commands
• Multilingual - English, Japanese, Simplified Chinese, Traditional Chinese support

For detailed documentation, see:

• Configuration Reference
• Watch Mode Guide
• History Guide
• I18N Guide
• Template System
• Plugin System

Configuration Examples

You can edit the configuration file (~/.config/cmdrun/commands.toml) directly for advanced features:

# Commands with dependencies
[commands.deploy]
description = "Deploy to production"
cmd = "ssh user@server 'cd /app && git pull && npm install && pm2 restart app'"
deps = ["test"]  # Deploy only after tests pass
confirm = true   # Ask for confirmation before running

[commands.test]
description = "Run tests"
cmd = "npm test"

# Using environment variables
[commands.backup]
description = "Create backup"
cmd = "rsync -avz ~/projects/ ${BACKUP_PATH:?BACKUP_PATH not set}"

# Platform-specific commands
[commands.open]
description = "Open browser"
cmd.unix = "open http://localhost:3000"
cmd.windows = "start http://localhost:3000"
cmd.linux = "xdg-open http://localhost:3000"

Color Output Control

cmdrun automatically detects whether it's outputting to a terminal and adjusts color output accordingly.

Controlling Color Output

Method 1: Using --color flag (recommended)

# Disable colored output
cmdrun list --color=never

# Force colored output (even when piping)
cmdrun list --color=always | less -R

# Automatic detection (default)
cmdrun list --color=auto

Method 2: Using NO_COLOR environment variable

# Disable colored output for a single command
NO_COLOR=1 cmdrun list

# Disable colored output globally
export NO_COLOR=1
cmdrun list

Method 3: Automatic detection (default behavior)

# Colors enabled when outputting to terminal
cmdrun list

# Colors automatically disabled when piping
cmdrun list | grep build
cmdrun list > commands.txt

CI/CD Usage

For CI/CD environments, you can disable colors to keep logs clean:

# GitHub Actions
- name: Run tests
  run: cmdrun run test --color=never
  # or
  env:
    NO_COLOR: 1
  run: cmdrun run test

# GitLab CI
script:
  - cmdrun run deploy --color=never

Priority Order

1. --color flag (highest priority)
2. NO_COLOR environment variable
3. Automatic TTY/pipe detection (default)

For more details, see the CLI Reference.

Testing

cmdrun maintains comprehensive test coverage across multiple categories:

Test Coverage

• Current Coverage: 70%+ (target: 85%)
• Test Categories: Unit, Integration, E2E, Security, Property-based
• Platform Coverage: Linux, macOS, Windows
• Automated CI/CD: GitHub Actions with coverage reporting

Running Tests

# Run all tests
cargo test

# Run with coverage (requires cargo-tarpaulin)
cargo install cargo-tarpaulin
cargo tarpaulin --out Html --output-dir ./coverage

# Run specific test categories
cargo test --test integration
cargo test --test e2e_tests
cargo test --test security

# Generate comprehensive coverage report
cargo tarpaulin --lib --bins --tests --out Xml --out Html \
  --output-dir ./coverage --timeout 600

Coverage Reports

Coverage reports are automatically generated for every PR and push to main branch:

• Codecov Integration: Detailed coverage analysis with diff coverage
• Automated Thresholds: CI fails if coverage drops below 55%
• HTML Reports: Detailed coverage reports available as GitHub Actions artifacts
• PR Comments: Coverage percentage automatically posted on pull requests

Test Structure

tests/
├── integration/        # Integration tests (command workflows)
├── e2e/               # End-to-end tests (CLI behavior)
├── unit_i18n.rs      # Internationalization tests
└── README.md          # Test documentation

See Test Documentation for detailed testing information.

Documentation

User Guide

• CLI Reference
• Configuration Reference
• Internationalization (i18n)
• Watch Mode
• History
• FAQ
• Recipes
• Troubleshooting

Quality & Testing

• Test Documentation
• Coverage Reports (Codecov)
• Mutation Testing Guide 🧬
• Performance Benchmarks
• CI/CD Pipeline (GitHub Actions)

Feature Guides

• Environment Management
• Template System
• Plugin System

Plugin Development

• Plugin API Specification
• Plugin Development Guide
• Sample Plugins

Technical Documentation

• Architecture
• Performance
• Performance Guide
• Security
• Cross-platform Support
• Distribution

License

This project is licensed under the MIT License.

---

Developer: sanae.a.sunny@gmail.com