cmd-runner

A smart command runner that finds and executes commands across different build systems and project types.

Why? Working across multiple projects with different tech stacks (Rust/Cargo, Node/npm/bun, Python/uv, Go, etc.) means remembering different commands for the same tasks. Instead of trying to recall whether it's npm run test, cargo test, go test, or make test, or wondering whether this Node project uses npm run test or bun test, simply use cmdr test in any project.

Example

# In a Rust project
$ cmdr test
Running: cargo test

# In a Node project with bun
$ cmdr test
Running: bun run test

# In a project with a Makefile
$ cmdr format
Running: make format

# Or use the shorter alias
$ cr test
Running: cargo test

Installation

go install github.com/osteele/cmd-runner/cmd/cmdr@latest

This installs the binary as cmdr. For an even shorter command, you can install the cr alias:

# Preview what will be changed (dry-run)
cmdr install-alias --dry-run

# Install the alias
cmdr install-alias

Or manually create an alias in your shell configuration:

alias cr=cmdr

# For an ultra-short alias, you could even use punctuation:
alias ,=cmdr   # Now you can type: , test
alias @=cmdr   # Now you can type: @ build

Or install from source:

git clone https://github.com/osteele/cmd-runner.git
cd cmd-runner
go install ./cmd/cmdr

Usage

cmdr <command> [args...]
cmdr install-alias [--dry-run]  # Install 'cr' alias to shell config

Examples:

cmdr format           # Runs format or fmt command
cmdr test             # Runs test command
cmdr run              # Runs run, dev, or serve command
cmdr build -- --prod  # Runs build with additional arguments

# Or with the short alias (after installing)
cr test               # Same as cmdr test
cr format             # Same as cmdr format

Supported Commands

format / fmt - Code formatting
run / dev / serve / start - Run development server or application
build - Build the project
lint - Run linters
typecheck - Run type checker (TypeScript, Python, Rust, Go)
test - Run tests
check - Run lint, typecheck, and test together (uses native check if available, otherwise synthesizes)
fix - Auto-fix issues (uses native fix if available, otherwise runs format and lint --fix)
clean - Clean build artifacts
install / setup - Install dependencies

Smart Command Synthesis

check: If no native check command exists, automatically runs lint, typecheck, and test in sequence
fix: If no native fix command exists, automatically runs format and lint --fix
typecheck: Errors if the project doesn't support type checking (no TypeScript, Python with pyright/mypy, Rust, or Go)

Supported Languages & Stacks

JavaScript/TypeScript

Package Managers: bun, pnpm, yarn, npm, deno
Type Checking: TypeScript (tsc)
Common Tools: biome, eslint, prettier

Python

Package Manager: uv (with pyproject.toml)
Type Checking: pyright, mypy
Common Tools: ruff, pytest

Rust

Build System: cargo
Type Checking: Built-in (cargo check)
Common Tools: clippy, rustfmt

Go

Build System: go modules
Type Checking: Built-in (go build)
Common Tools: go vet, gofmt

Java/Kotlin

Build Systems: gradle, maven
Type Checking: Built-in compilation

Supported Build Systems

The tool searches for commands in the following order:

mise - .mise.toml (polyglot runtime manager)
just - justfile or Justfile (command runner)
make - Makefile or makefile (classic build tool)
Node.js - package.json with bun/pnpm/yarn/npm
Rust - Cargo.toml (cargo)
Go - go.mod (go modules)
Python - pyproject.toml with uv
Java/Kotlin - build.gradle[.kts] (gradle) or pom.xml (maven)

Search Strategy

First searches in the current directory
Then searches in the project root (determined by .jj or .git directory)
Tries command aliases (e.g., fmt for format, dev for run)

Features

Intelligent command aliasing (e.g., run → dev → serve)
Searches both current directory and project root
Passes through additional arguments to the underlying command
Supports all major build systems and package managers

License

MIT License

osteele / cmd-runner