v2.1.0 documentation

RunCmd Documentation

Everything you need to install, configure, and operate the RunCmd universal script runner across macOS, Linux, and Windows.

Download Script Start Installing

Table of contents

Overview Installation Usage & Resolution Debug & Checks Environment Runner Capabilities Git-Flow Toolkit Quick Commands Resources

What is RunCmd?

RunCmd is a universal script runner that separates runtime setup from your business logic. Runner scripts (runcmd.sh, runcmd.bat) handle Bun installation, environment loading, cross-platform path resolution, and built-in tooling so your .mjs scripts stay focused on logic.

  • Cross-platform: Seamless on macOS, Linux, and Windows.
  • Zero config: Automatically installs Bun and required tooling.
  • Robust: Atomic updates, safe self-formatting, and exit-code propagation.
  • Integrated tooling: oxlint, oxfmt, shfmt, and JSON validation built in.

Install (Unix / macOS)

Download and make the runner executable:

curl -fsSL https://lguzzon.github.io/runcmd/runcmd.sh -o runcmd.sh
chmod +x runcmd.sh

Run the default script or pass a target:

./runcmd.sh
./runcmd.sh +r ./my-script.mjs --flag value
./runcmd.sh +check

Install (Windows)

Place runcmd.bat alongside your script or in PATH. Usage examples:

runcmd.bat
runcmd.bat +d
runcmd.bat +r my-script.mjs --flag
runcmd.bat +check

Supported files: .js, .mjs, .ts, and .py. Bun and supporting tools auto-install as needed.

v2.1.0: +check mode and +r path selection now available on Windows.

Usage & Script Resolution

Runner scripts locate your target script automatically. Priority:

  1. Explicit path: +r <path> (both platforms).
  2. Current directory: <runner_name>.mjs.
  3. Runner directory: <runner_name>.mjs alongside the runner.

Example for a custom runner:

cp runcmd.sh build.sh
echo "console.log("Building...");" > build.mjs
./build.sh

Debugging & Code Quality

Debug modes

  • ./runcmd.sh +debug or DEBUG=1 ./runcmd.sh
  • ./runcmd.sh +dd (file operations) or +ddd (full echo)
  • Windows: runcmd.bat +d, +dd, +ddd, +d0 to disable

Checks & formatting

  • ./runcmd.sh +check — formats shell scripts, sorts JSON, runs oxlint and oxfmt.
  • runcmd.bat +check — check mode on Windows: oxlint and oxfmt only (v2.1.0+).
  • Manual: bunx oxfmt --write .
  • Manual: bunx oxlint --fix-dangerously .
  • Shell: bunx shfmt -w -bn -ci -i 2 -s *.sh

Environment & Configuration

  • .env loading order: script directory .env, then current directory .env (overrides).
  • Env vars: DEBUG, RUNCMD_NO_UPDATE, RUNCMD_HOME.
  • Exit codes: Target script exit codes propagate to the caller.

runcmd.sh (Unix / macOS)

  • Installs Bun to ~/.bun if missing.
  • Safe self-formatting with rollback protection.
  • Cross-platform path resolution with Bun fallback.
  • Hardened security: no eval in .env loading.
  • Timing and debug logging utilities.

runcmd.bat (Windows)

  • Supports .js, .mjs, .ts, and .py.
  • Auto-installs tooling via PowerShell when needed.
  • +check mode for lint/format/validate audits.
  • +r <path> flag for explicit script targeting.
  • Multiple debug levels (+d, +dd, +ddd, +d0).
  • Delayed variable expansion for complex operations.

Git-Flow Toolkit

High-level git-flow automation lives in scripts/. Common actions:

  • bun scripts/git-flow.js init — initialize git-flow.
  • bun scripts/git-flow.js start feature my-feature — start a branch.
  • bun scripts/git-flow.js finish feature my-feature — finish and merge.
  • bun scripts/git-flow.js release start --bump minor — start a release with auto-versioning.
  • bun scripts/git-flow.js release finish --tag v1.1.0 --message "Release" — tag and merge.
  • bun scripts/git-flow.js hotfix finish --tag v1.0.1 --message "Hotfix" — complete a hotfix.

Quick Commands

Core

  • ./runcmd.sh — run default script.
  • ./runcmd.sh +r ./task.mjs --flag — run specific script.
  • ./runcmd.sh +check — format and validate.

Windows

  • runcmd.bat — run default script.
  • runcmd.bat +r script.mjs — run specific script.
  • runcmd.bat +check — format and validate.
  • runcmd.bat +d — enable debug output.

Resources