Commands Overview

workspace-utils provides commands for task execution, dependency-aware builds, development, cleanup, cache management, and graph inspection. Commands share package selection, affected detection, dry-run, and failure controls where applicable.

Command Summary

Advanced selection

Use repeatable filters to compose package sets. A trailing ellipsis includes dependencies, a leading ellipsis includes dependents, ./ matches package directories, and ! excludes matches.

wsu run test --filter 'app...'
wsu run test --filter '...core' --filter '!docs'
wsu build --affected
wsu build --since origin/main

Add --dry-run to inspect a plan without executing or mutating the workspace. Add global --output json for newline-delimited execution events.

Quick Reference

wsu run

wsu run <script> [options]

Execute any script across multiple packages in parallel (by default) or sequentially.

Package.json setup:

{
    "scripts": {
        "test": "wsu run test",
        "lint": "wsu run lint --sequential",
        "typecheck": "wsu run typecheck --concurrency 8"
    }
}

Usage:

npm run test       # Run tests in parallel
npm run lint       # Run linting sequentially
npm run typecheck  # Custom concurrency

wsu build

wsu build [options]

Build packages in dependency order using topological sorting. Packages are built in batches where each batch can run in parallel.

Package.json setup:

{
    "scripts": {
        "build": "wsu build",
        "build:apps": "wsu build --filter 'apps/*'",
        "build:slow": "wsu build --concurrency 2"
    }
}

Usage:

npm run build       # Build all packages
npm run build:apps  # Build only apps
npm run build:slow  # Limit batch concurrency

wsu dev

wsu dev [options]

Start development servers with live log streaming. Designed for long-running processes with real-time output.

Package.json setup:

{
    "scripts": {
        "dev": "wsu dev",
        "dev:scope": "wsu dev --filter '@scope/*'",
        "dev:limited": "wsu dev --concurrency 3"
    }
}

Usage:

npm run dev         # Start all dev servers
npm run dev:scope   # Start scoped packages
npm run dev:limited # Limit concurrent servers

wsu clean

wsu clean [options]

Remove node_modules directories from the workspace root and all packages.

Package.json setup:

{
    "scripts": {
        "clean": "wsu clean",
        "clean:apps": "wsu clean --filter 'apps/*'",
        "reinstall": "wsu clean && npm install"
    }
}

Usage:

npm run clean       # Remove all node_modules
npm run clean:apps  # Clean only app packages
npm run reinstall   # Clean and reinstall

Global Options

All commands support these common options:

Filtering

• --filter <pattern> - Filter packages using glob patterns
• Examples: "@scope/*", "apps/*", "*-utils", "*frontend*"

Concurrency

• --concurrency <number> - Maximum concurrent processes (default: 4)
• Applies to parallel execution and batch processing

Help

• --help - Show command-specific help and options

Execution Modes

Parallel Execution

Used by: run (default), dev Behavior: All matching packages execute simultaneously Best for: Tests, linting, development servers

npm run test  # with "test": "wsu run test" in package.json
# ✅ Runs tests in all packages at the same time

Sequential Execution

Used by: run (with --sequential flag) Behavior: Packages execute one after another Best for: Resource-intensive tasks, ordered operations

npm run build:sequential  # with "build:sequential": "wsu run build --sequential"
# ✅ Runs builds one package at a time

Dependency-Aware Execution

Used by: build Behavior: Packages are grouped into batches based on dependencies Best for: Building, publishing, dependency-critical operations

npm run build  # with "build": "wsu build" in package.json
# ✅ Builds dependencies first, then dependents

Package Manager Detection

workspace-utils automatically detects your package manager:

The detected package manager is used for all script execution (e.g., bun run test, pnpm run test, npm run test).

Error Handling

Exit Behavior

• Single failure in parallel mode: Other packages continue running
• Single failure in sequential mode: Execution stops immediately
• Single failure in build mode: Current batch fails, subsequent batches are skipped

Exit Codes

• 0 - All packages executed successfully
• 1 - One or more packages failed
• 2 - Configuration or setup error

Output Format

All commands provide consistent, color-coded output:

🚀 Starting operation...
📁 Workspace root: /path/to/workspace
📦 Found X packages
✅ Running "script" in Y packages
🔧 Package manager: detected-pm
⚡ Execution mode: parallel/sequential/dependency-order

[package-1] Starting: pm run script
[package-2] Starting: pm run script
[package-1] ✅ Completed in 1,234ms
[package-2] ❌ Failed with exit code 1

📊 Execution Summary:
✅ Successful: 1
❌ Failed: 1
⏱️  Total duration: 2,345ms

Best Practices

Choose the Right Command

• run for most script execution (tests, linting, utilities)
• build when package dependencies matter
• dev for long-running development processes
• clean to remove node_modules for fresh installs

Use Filtering Effectively

{
    "scripts": {
        "test:packages": "wsu run test --filter 'packages/*'",
        "dev:apps": "wsu dev --filter 'apps/*'",
        "build:company": "wsu build --filter '@company/*'"
    }
}

Optimize Concurrency

{
    "scripts": {
        "build:slow": "wsu run build --concurrency 2",
        "test:fast": "wsu run test --concurrency 8",
        "dev": "wsu dev --concurrency 4"
    }
}

Next Steps

Dive deeper into each command:

• run command - Detailed script execution options
• build command - Dependency-aware building
• dev command - Development server management
• clean command - Remove node_modules directories