Skip to content

A beautiful process runner for parallel commands with interactive filtering and real-time output control.

License

Notifications You must be signed in to change notification settings

jenslys/sinfonia

Repository files navigation

sinfonia 🎵

A beautiful process runner for parallel commands with interactive filtering and real-time output control.

npm version License: MIT PRs Welcome

sinfonia (n.) - from Italian, meaning "symphony": a harmonious combination of elements working together as one, just like an orchestra performing multiple parts in perfect coordination.

Features ✨

  • 🚀 Run multiple commands in parallel with a single terminal window
  • 👥 Group related processes for better organization
  • 🎯 Filter and focus on specific process or group outputs using arrow keys
  • 🎨 Search through logs and process names in real-time
  • 🎨 Color-coded outputs for easy process identification
  • ⌨️ Interactive process/group control (start/stop/restart)
  • 📊 Real-time output monitoring
  • 🔄 Process state management
  • 💾 Configurable output buffer size
  • 🔗 Optional dependency ordering with ready state detection (via config file)
  • 📝 Automatic log file generation with customizable paths
  • 📋 JSON Schema for config file validation and IDE support

Installation 📦

# Using bun
bun install -g sinfonia

# Using npm
npm install -g sinfonia

# Using yarn
yarn global add sinfonia

Usage 🛠️

Sinfonia offers two modes of operation:

Simple Mode (CLI)

For basic usage without dependencies:

# Single command
sinfonia "web=npm run dev"

# Multiple commands
sinfonia "web=npm run dev" "api=npm run server"

# With groups
sinfonia "frontend:web=npm run dev" "backend:api=npm run server"

Features available in CLI mode:

  • Basic command running (name=cmd)
  • Basic grouping (group:name=cmd)
  • Buffer size (-b, --buffer-size)
  • Log file (-l, --log-file)
  • Config file (-c, --config)

Advanced Mode (Config File)

For complex setups with dependencies, use a config file. You can generate a starter config with:

# Generate a starter config file (sinfonia.json)
sinfonia init

# Generate and overwrite existing config
sinfonia init --force

Then run it with:

# Uses sinfonia.json by default
sinfonia

# Or specify a different config file
sinfonia -c custom.json

Additional features in config mode:

  • Everything from CLI mode
  • Dependencies between commands (dependsOn)
  • Ready patterns for dependencies (readyPatterns)
  • Per-command and per-group color customization
  • Reusable configuration

Example config file (sinfonia.json):

{
  "$schema": "https://raw.githubusercontent.com/jenslys/sinfonia/main/schema.json",
  "commands": [
    {
      "name": "DB",
      "cmd": "docker compose up",
      "color": "blue"
    },
    {
      "name": "API",
      "cmd": "npm run api",
      "group": "BACKEND",
      "dependsOn": ["DB"],
      "readyPatterns": {
        "db": "Database system is ready"
      }
    },
    {
      "name": "WORKER",
      "cmd": "npm run worker",
      "group": "BACKEND",
      "dependsOn": ["DB"],
      "readyPatterns": {
        "db": "Database system is ready"
      }
    },
    {
      "name": "WEB",
      "cmd": "npm run dev",
      "group": "FRONTEND",
      "dependsOn": ["API"],
      "readyPatterns": {
        "api": "Server started on port"
      }
    }
  ],
  "groups": [
    {
      "name": "BACKEND",
      "color": "cyan"
    },
    {
      "name": "FRONTEND",
      "color": "magenta"
    }
  ],
  "options": {
    "bufferSize": 100
  }
}

The config file supports JSON Schema validation for better IDE support and validation. Groups are automatically created from command group fields - you only need to define them in the groups array if you want to customize their properties (like colors).

Options

# Custom buffer size
sinfonia -b 200 "web=npm run dev" "api=npm run server"

# Enable logging to file
sinfonia -l "output_{timestamp}.log" "web=npm run dev" "api=npm run server"

# Use custom config file (defaults to sinfonia.json)
sinfonia -c my-config.json

Controls 🎮

Key Action
↑/↓ Navigate processes/groups
r Restart process/group
s Stop/Start process/group
f Search in logs
j/k Scroll logs up/down
u/d Page up/down (half screen)
Space Toggle auto-follow logs
Ctrl+C Exit all processes

Log Navigation

The log viewer supports both manual and auto-follow modes:

  • Use j/k for line-by-line scrolling
  • Use u/d for faster page-based scrolling
  • Press Space to toggle between manual scrolling and auto-follow mode
  • Auto-follow mode automatically shows the latest logs as they arrive
  • Any scroll action automatically switches to manual mode

Preview

preview-screenshot

License 📄

MIT

About

A beautiful process runner for parallel commands with interactive filtering and real-time output control.

Topics

Resources

License

Stars

Watchers

Forks