conqr

Dead-simple TUI process runner, written in Go.

Usage

Command Line Arguments

conqr 'npm run dev' 'npm run build:emails' 'npm run worker'

Customize process names with the 'name'='command' syntax:

conqr 'Dev Server'='npm run dev' 'Build Process'='npm run build' 'Worker'='npm run worker'

Configuration File

Create a conqr.json or .conqr.json file in your project directory.

Simple commands:

{
  "commands": {
    "Dev Server": "npm run dev",
    "Build Process": "npm run build",
    "Worker": "npm run worker"
  }
}

Extended commands with restart options:

{
  "commands": {
    "Dev Server": {
      "command": "npm run dev",
      "restart": {
        "policy": "on-error",
        "delay": 2000
      }
    },
    "Worker": {
      "command": "npm run worker",
      "restart": {
        "policy": "on-exit",
        "delay": 5000
      }
    }
  }
}

Then run:

conqr

CLI arguments take precedence over config files.

Restart Configuration

Restart policies:

• "never": no automatic restart
• "on-error": restart only when a process exits with a non-zero code
• "on-exit": restart whenever a process exits

Global restart settings apply to all config-file commands:

{
  "restart": {
    "policy": "on-error",
    "delay": 2000
  },
  "commands": {
    "Dev Server": "npm run dev",
    "Worker": "npm run worker"
  }
}

Per-process restart settings override global settings:

{
  "restart": {
    "policy": "on-error",
    "delay": 2000
  },
  "commands": {
    "Dev Server": "npm run dev",
    "Worker": {
      "command": "npm run worker",
      "restart": {
        "policy": "on-exit",
        "delay": 5000
      }
    }
  }
}

Process Groups

Group commands in the sidebar and view merged logs per group. Use the object form for grouped commands:

{
  "defaultGroup": "services",
  "commands": {
    "api": { "command": "npm run api", "group": "services" },
    "ssr": { "command": "npm run ssr", "group": "services" },
    "worker": { "command": "npm run worker", "group": "services" },
    "cf": { "command": "cloudflared tunnel run", "group": "tunnels" },
    "emails": { "command": "npm run build:emails", "group": "build" }
  }
}

• group: optional label used for sidebar sections and merged log views
• defaultGroup: optional group selected on startup (falls back to "All processes" if missing)
• Simple string commands cannot carry a group; use the object form instead
• Select a group row to see merged logs from all processes in that group
• Select an indented process row to see logs for one process
• Stop/restart (s/r) work on individual process rows only

JSON Schema

For IDE autocomplete and validation, add a $schema reference:

{
  "$schema": "https://raw.githubusercontent.com/bohdan-shulha/conqr/main/conqr.schema.json",
  "commands": {
    "Dev Server": "npm run dev",
    "Build": "npm run build"
  }
}

Demo

Try it with the included demo scripts:

go run . 'node demo/logger1.js' 'node demo/logger2.js' 'node demo/logger3.js'

Features

• Run multiple commands concurrently
• Two-pane terminal interface with process statuses and logs
• Process groups with merged log views per group
• Unified "All processes" log view
• ANSI color support in logs
• Automatic error detection from common error patterns and red ANSI output
• Auto-scroll to bottom while new logs arrive
• Mouse wheel and keyboard scrolling
• Raw log mode with l
• Manual process stop with s
• Manual process restart with r
• Automatic process restart with configurable policies
• Graceful process-group shutdown on quit

Keyboard Controls

• Arrow Left/Right: switch focus between sidebar and logs
• Arrow Up/Down: navigate commands or scroll logs
• PageUp/PageDown: scroll logs 10 lines
• Home/End: jump to top or bottom
• s: stop selected process
• r: restart selected process
• l: toggle raw log mode
• q or Ctrl+C: quit

Requirements

• For npm installs: Node.js 18 or newer
• For source builds: Go 1.25 or newer
• Prebuilt npm binaries are published for macOS, Linux, and Windows on amd64 and arm64

Installation

Install from npm:

npm install -g conqr

The npm package preserves the existing conqr command and launches the bundled Go binary for your platform.

Install from source:

go install github.com/bohdan-shulha/conqr@latest

Or build locally:

make build
./bin/conqr 'command1' 'command2' 'command3'

Development

make test
go run . 'command1' 'command2' 'command3'