spcrun

Run multiple project commands in parallel from a simple JSON config.

spcrun discovers a spcrun.config.json in your current working directory, then starts each configured command in its respective subfolder, prefixing output with a colored tag for easy scanning.

Install

From source (global CLI):

npm install
npm run build
npm install -g .
spcrun --help

From source (local/dev without global install):

npm install
npm run dev -- --help
# or
npm run dev-select

Note: Installing globally from this repo (npm install -g .) makes the spcrun command available on your PATH.

Usage

spcrun [options]

Options:

• -s, --select — interactively select which path entries to run.
• -c, --config <path> — path to a config file (defaults to ./spcrun.config.json).

Behavior:

• Without --select, only entries with isEnabled: true are run.
• With --select, you choose one or more paths interactively; isEnabled is ignored.
• Each command runs with shell: true in the directory resolved from process.cwd() + path.
• Output from each process is line-prefixed with a colored [path] label.
• All environment variables from the parent process are passed through.

Exit codes:

• Exits 0 if all commands exit with code 0.
• Exits 1 if any command exits non‑zero (also prints how many failed).

Stopping:

• Press Ctrl+C to stop; spcrun will attempt to kill all child processes before exiting.
• On Windows, Ctrl+Break is also handled.

Config

Default location: ./spcrun.config.json (override with --config path/to/file.json).

Schema:

{
  "commands": [
    {
      "path": "string",
      "run": "string",
      "isEnabled": "boolean (optional)"
    }
  ]
}

Field notes:

• path: Folder (relative to where you run spcrun) to use as the working directory.
• run: The command to execute (e.g. npm run dev, pnpm start, vite, node server.js).
• isEnabled (optional): If true, the entry runs by default when not using --select.

Minimal example

{
  "commands": [
    { "path": "apps/web", "run": "npm run dev", "isEnabled": true },
    { "path": "packages/ui", "run": "npm run dev", "isEnabled": true }
  ]
}

Passing extra args to npm scripts

{
  "commands": [
    { "path": "apps/web", "run": "npm run dev -- --port 3000", "isEnabled": true },
    { "path": "apps/admin", "run": "npm run dev -- --port 3001", "isEnabled": true }
  ]
}

Examples

Run all enabled services:

spcrun

Interactively choose which to run:

spcrun --select

Use a custom config path:

spcrun --config ./configs/spcrun.local.json

Output

Each process prints prefixed lines, e.g.:

[apps/web] ready in 500ms
[packages/ui] built successfully

Different colors are used per process for quick visual separation. A spinner shows while a process is starting and stops on first output.

Troubleshooting

• "Config file not found": Ensure spcrun.config.json exists in the current directory or pass --config.
• "Invalid JSON": Fix JSON syntax errors reported for your config file.
• "Invalid command at index …": Each entry must include non‑empty path and run strings.
• Commands not starting: Confirm the path exists and the command runs manually in that folder.

License

MIT