cargo-run

MIT or Apache 2.0 licensed

A powerful, fast, and developer-friendly CLI tool for managing project scripts in Rust
Think npm scripts, make, or just — but built specifically for the Rust ecosystem with modern CLI best practices.

Why `cargo-run`?

Stop writing one-off shell scripts. cargo-run provides a unified, type-safe way to manage all your project automation:

✅ Zero runtime dependencies — Single binary, fast startup
✅ Cross-platform — Works on Windows, macOS, and Linux
✅ Modern CLI UX — Shell completions, dry-run mode, helpful errors
✅ Powerful features — Script chaining, environment variables, toolchain support
✅ CI/CD ready — Validation command catches errors early
✅ Rust-native — Built with Rust, for Rust projects

Quick Comparison

Feature	`cargo-run`	`make`	`just`	`npm scripts`
Zero dependencies	✅	✅	✅	❌ (Node.js)
Shell completions	✅	⚠️	✅	✅
Dry-run mode	✅	❌	✅	❌
Validation	✅	❌	⚠️	❌
Toolchain support	✅	❌	❌	❌
Environment precedence	✅	⚠️	⚠️	✅

📦 Installation

cargo install cargo-run

After installation, you'll have multiple ways to invoke the tool:

cargo script — Recommended: Use as a Cargo subcommand (e.g., cargo script run build)
cargo-script — Direct binary invocation
cgs — Short alias (used in examples below for brevity)

Note: When installed via cargo install, the cargo-script binary is automatically available in your PATH, enabling cargo script subcommand usage.

⚡ Quick Start

Initialize a Scripts.toml file:

# Using Cargo subcommand (recommended)

cargo script init


# Or using direct binary

cgs init

Run a script:

# Using Cargo subcommand

cargo script run build


# Or using direct binary

cgs run build

Preview what would run (dry-run):
```
cargo script run build --dry-run
```
Validate your configuration:
```
cargo script validate
```
Show all available scripts:
```
cargo script show
```

That's it! You're ready to go. 🎉

💡 Tip: Using cargo script integrates seamlessly with Cargo's ecosystem and provides a familiar interface for Rust developers.

📚 Features

Core Features

Script Execution — Run scripts defined in Scripts.toml
Script Chaining — Compose complex workflows with include
Environment Variables — Global, script-specific, and command-line overrides
Multiple Interpreters — bash, zsh, PowerShell, cmd, or custom
Toolchain Support — Rust toolchains via rustup, Python versions
Requirements Checking — Validate tool versions before execution

Developer Experience

Shell Completions — Tab completion for bash, zsh, fish, and PowerShell
Dry-Run Mode — Preview execution without side effects
Helpful Errors — Actionable error messages with suggestions
Validation — Catch configuration errors early
Performance Metrics — Track script execution times

📖 Usage Guide

Initialize `Scripts.toml`

Create a new Scripts.toml file with sensible defaults:

# Using Cargo subcommand (recommended)

cargo script init


# Or using direct binary

cgs init

This creates a Scripts.toml file with:

[global_env]



[scripts]

dev = "cargo run"

build = { command = "cargo build", env = { RUST_LOG = "info" } }

release = "cargo build --release"

test = { command = "cargo test", env = { RUST_LOG = "warn" } }

doc = "cargo doc --no-deps --open"

Run Scripts

# Using Cargo subcommand (recommended)

cargo script run build


# Simple script

cgs run build


# With environment variable override

cargo script run test --env RUST_LOG=debug


# Preview execution (dry-run)

cargo script run release --dry-run

Script Configuration

Simple Script

[scripts]

build = "cargo build"

Script with Metadata

[scripts]

build = {

    command = "cargo build",

    info = "Build the project in release mode",

    env = { RUST_LOG = "info" }

}

Script with Interpreter

[scripts]

deploy = {

    interpreter = "bash",

    command = "./scripts/deploy.sh",

    info = "Deploy to production"

}

Script Chaining (Includes)

[scripts]

prepublish_clean = "cargo clean"

prepublish_doc = "cargo doc --no-deps"

prepublish_dry = "cargo publish --dry-run"

prepublish_check = "cargo package --list"



prepublish = {

    include = ["prepublish_clean", "prepublish_doc", "prepublish_dry", "prepublish_check"],

    info = "Run all prepublish checks"

}

Script with Requirements

[scripts]

deploy = {

    command = "./deploy.sh",

    requires = ["docker >= 19.03", "kubectl >= 1.18"],

    toolchain = "stable",

    info = "Deploy application"

}

CI/CD-like Format

[scripts.build]

script = "build"

command = "cargo build"

info = "Build the project"



[scripts.test]

script = "test"

command = "cargo test"

requires = ["rustup >= 1.70"]

toolchain = "stable"

Environment Variables

Global Environment Variables

[global_env]

RUST_BACKTRACE = "1"

RUST_LOG = "info"

Script-Specific Environment Variables

[scripts]

test = {

    command = "cargo test",

    env = { RUST_LOG = "debug" }

}

Command-Line Overrides

# Using Cargo subcommand

cargo script run test --env RUST_LOG=trace


# Or using direct binary

cgs run test --env RUST_LOG=trace

Precedence Order:

Command-line overrides (--env)
Script-specific (env in script)
Global ([global_env])

Show All Scripts

# Using Cargo subcommand (recommended)

cargo script show


# Or using direct binary

cgs show

Output:

📋 Available Scripts:
  • build     - Build the project
  • test      - Run tests
  • release   - Build release version
  • prepublish - Run all prepublish checks

Dry-Run Mode

Preview what would be executed without actually running it:

# Using Cargo subcommand (recommended)

cargo script run prepublish --dry-run


# Or using direct binary

cgs run prepublish --dry-run

Output:

DRY-RUN MODE: Preview of what would be executed
================================================================================

📋  Would run script: [ prepublish ]
    Description: Run all prepublish checks
    Would run include scripts:
      📋  Would run script: [ prepublish_clean ]
          Command: cargo clean

      📋  Would run script: [ prepublish_doc ]
          Command: cargo doc --no-deps

      📋  Would run script: [ prepublish_dry ]
          Command: cargo publish --dry-run

      📋  Would run script: [ prepublish_check ]
          Command: cargo package --list

No commands were actually executed.

Shell Completions

Enable tab completion for a better developer experience:

Bash:

# Using Cargo subcommand (recommended)

cargo script completions bash > ~/.bash_completion.d/cargo-script

# Or system-wide:

cargo script completions bash | sudo tee /etc/bash_completion.d/cargo-script


# Or using direct binary

cgs completions bash > ~/.bash_completion.d/cgs

Zsh:

mkdir -p ~/.zsh/completions

# Using Cargo subcommand (recommended)

cargo script completions zsh > ~/.zsh/completions/_cargo-script

# Or using direct binary

cgs completions zsh > ~/.zsh/completions/_cgs

# Add to ~/.zshrc:

fpath=(~/.zsh/completions $fpath)
autoload -U compinit && compinit

Fish:

# Using Cargo subcommand (recommended)

cargo script completions fish > ~/.config/fish/completions/cargo-script.fish

# Or using direct binary

cgs completions fish > ~/.config/fish/completions/cgs.fish

PowerShell:

# Using Cargo subcommand (recommended)
cargo script completions power-shell > $PROFILE
# Or using direct binary
cgs completions power-shell > completions.ps1
. .\completions.ps1

After installation, restart your shell and enjoy tab completion! 🎉

Validation

Catch configuration errors before they cause problems:

# Using Cargo subcommand (recommended)

cargo script validate


# Or using direct binary

cgs validate

What it checks:

✅ TOML syntax validity
✅ Script references in include arrays
✅ Tool requirements (checks if tools are installed)
✅ Toolchain requirements (checks if Rust/Python toolchains are installed)

Example output:

✓ All validations passed!

With errors:

❌ Validation Errors:
  1. Script 'release': Script 'release' references non-existent script 'build'
  2. Script 'deploy': Required tool 'docker' is not installed or not in PATH

✗ Found 2 error(s)

CI/CD Integration:

# .github/workflows/ci.yml
- name: Validate Scripts.toml
  run: cargo script validate

Error Messages

cargo-run provides helpful, actionable error messages:

Script Not Found:

$ cargo script run buid

❌ Script not found


Error:

  Script 'buid' not found in Scripts.toml


Did you mean:

  • build


Suggestion:

  Use 'cargo script show' to see all available scripts

Invalid TOML:

$ cargo script run test

❌ Invalid TOML syntax


Error:

  File: Scripts.toml

  Message: invalid table header

  Line 10: See error details above


Suggestion:

  Check your Scripts.toml syntax. Common issues:

  - Missing quotes around strings

  - Trailing commas in arrays

  - Invalid table syntax

Missing Tool:

$ cargo script run deploy

❌ Required tool not found


Error:

  Tool 'docker' is not installed or not in PATH


Suggestion:

  Install docker and ensure it's available in your PATH

Use Cases

Development Workflow

[scripts]

dev = "cargo run"

test = "cargo test"

test-watch = { command = "cargo watch -x test", requires = ["cargo-watch"] }

lint = "cargo clippy -- -D warnings"

fmt = "cargo fmt --check"

check = { include = ["fmt", "lint", "test"], info = "Run all checks" }

CI/CD Pipeline

[scripts]

ci = {

    include = ["check", "test", "build"],

    info = "Run CI pipeline"

}



[scripts.check]

command = "cargo clippy -- -D warnings"



[scripts.test]

command = "cargo test --all-features"



[scripts.build]

command = "cargo build --release"

Multi-Language Projects

[scripts]

build-rust = "cargo build"

build-python = {

    command = "python setup.py build",

    requires = ["python >= 3.8"],

    toolchain = "python:3.8"

}

build-all = { include = ["build-rust", "build-python"] }

Deployment Scripts

[scripts]

deploy-staging = {

    command = "./scripts/deploy.sh staging",

    requires = ["docker >= 19.03", "kubectl >= 1.18"],

    env = { ENV = "staging" }

}



deploy-production = {

    command = "./scripts/deploy.sh production",

    requires = ["docker >= 19.03", "kubectl >= 1.18"],

    env = { ENV = "production" }

}

🔧 Advanced Configuration

Custom Scripts Path

Use a different Scripts.toml file:

# Using Cargo subcommand

cargo script run build --scripts-path ./config/scripts.toml


# Or using direct binary

cgs run build --scripts-path ./config/scripts.toml

Performance Metrics

Script execution times are automatically tracked and displayed:

Scripts Performance
--------------------------------------------------------------------------------
✔️  Script: prepublish_clean        🕒 Running time: 1.23s
✔️  Script: prepublish_doc          🕒 Running time: 3.45s
✔️  Script: prepublish_dry          🕒 Running time: 2.10s

🕒 Total running time: 6.78s

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgments

Inspired by npm scripts, make, and just
Built with clap for excellent CLI experience
Uses colored for beautiful terminal output

Made with ❤️ for the Rust community

cargo-run 0.5.1