numux 2.10.4 → 2.12.0

package/dist/man/numux.1

@@ -0,0 +1,1134 @@
+.TH "NUMUX" "1" "April 2026" "2.12.0" "numux manual"
+.SH "NAME"
+\fBnumux\fR
+.P
+Terminal multiplexer with dependency orchestration\. Run multiple processes in a tabbed TUI with a dependency graph controlling startup order, readiness detection, and output capture between processes\.
+.P
+Works with zero configuration — pass commands as arguments, run a script across monorepo workspaces with \fB\-w\fP, or match multiple scripts with glob patterns like \fB'dev:*'\fP\|\. For advanced setups, define a typed config with conditional processes, file watching with auto\-restart, error detection, log persistence, and output capture — e\.g\. extract a port from one process's stdout and pass it to another process's command or env\.
+.P
+Inspired by \fBsst dev\fP and \fBconcurrently\fP
+.SH Install
+.P
+Requires 
+.UR https://bun.sh
+.I Bun
+.UE
+>= 1\.0\.
+.RS 2
+.nf
+bun install \-g numux
+.fi
+.RE
+.SH Usage
+.SS Quick start
+.RS 2
+.nf
+numux init
+.fi
+.RE
+.P
+This creates a starter \fBnumux\.config\.ts\fP with commented\-out examples\. Edit it, then run \fBnumux\fP\|\.
+.SS Config file
+.P
+Create \fBnumux\.config\.ts\fP (or \fB\|\.js\fP):
+.RS 2
+.nf
+import { defineConfig } from 'numux'
+
+export default defineConfig({
+  processes: {
+    db: {
+      command: 'docker compose up postgres',
+      readyPattern: 'ready to accept connections',
+    },
+    migrate: {
+      command: 'bun run migrate',
+      dependsOn: ['db'],
+    },
+    api: {
+      command: 'bun run dev:api',
+      dependsOn: ['migrate'],
+      readyPattern: 'listening on port 3000',
+    },
+    // String shorthand for simple processes
+    web: 'bun run dev:web',
+    // Interactive process — keyboard input is forwarded
+    confirm: {
+      command: 'sh \-c "printf \\'Deploy to staging? [y/n] \\' && read answer && echo $answer"',
+      interactive: true,
+    },
+  },
+})
+.fi
+.RE
+.P
+The \fBdefineConfig()\fP helper is optional — it provides type checking for your config\.
+.P
+Processes can be a string (shorthand for \fB{ command: "\.\.\." }\fP), \fBtrue\fP or \fB{}\fP (auto\-resolves to a matching \fBpackage\.json\fP script), or a full config object\.
+.P
+Then run:
+.RS 2
+.nf
+numux
+.fi
+.RE
+.SS Subcommands
+<!\-\- generated:subcommands \-\->
+.RS 2
+.nf
+numux init                         # Create a starter config file
+numux validate                     # Validate config and show process graph
+numux exec <name> [\-\-] <cmd>       # Run a command in a process's environment
+numux logs [name]                  # Open the log directory or a specific process log
+numux completions <shell>          # Generate shell completions (bash, zsh, fish)
+numux help [topic]                 # Show help for a topic
+.fi
+.RE
+<!\-\- /generated:subcommands \-\->
+
+.P
+\fBvalidate\fP respects \fB\-\-only\fP/\fB\-\-exclude\fP filters and shows processes grouped by dependency tiers\.
+.P
+\fBexec\fP runs a one\-off command using a process's configured \fBcwd\fP, \fBenv\fP, and \fBenvFile\fP — useful for migrations, scripts, or any command that needs the same environment:
+.RS 2
+.nf
+numux exec api \-\- npx prisma migrate
+numux exec web npm run build
+.fi
+.RE
+.P
+Set up completions for your shell:
+.RS 2
+.nf
+# Bash (add to ~/\.bashrc)
+eval "$(numux completions bash)"
+
+# Zsh (add to ~/\.zshrc)
+eval "$(numux completions zsh)"
+
+# Fish
+numux completions fish | source
+# Or save permanently:
+numux completions fish > ~/\.config/fish/completions/numux\.fish
+.fi
+.RE
+.SS Workspaces
+.P
+Run a \fBpackage\.json\fP script across all workspaces in a monorepo:
+.RS 2
+.nf
+numux \-w dev
+.fi
+.RE
+.P
+Reads the \fBworkspaces\fP field from your root \fBpackage\.json\fP, finds which workspaces have the given script, and spawns \fB<pm> run <script>\fP in each\. The package manager is auto\-detected from \fBpackageManager\fP field or lockfiles\.
+.P
+Composes with other flags:
+.RS 2
+.nf
+numux \-w dev \-n redis="redis\-server" \-\-colors
+.fi
+.RE
+.SS Ad\-hoc commands
+.RS 2
+.nf
+# Unnamed (name derived from command)
+numux "bun dev:api" "bun dev:web"
+
+# Named process
+numux \-n api="bun dev:api" \-n web="bun dev:web"
+.fi
+.RE
+.SS Script patterns
+.P
+Run package\.json scripts by name — any colon\-containing name is automatically recognized as a script reference:
+.RS 2
+.nf
+numux 'lint:eslint \-\-fix'  # runs: yarn run lint:eslint \-\-fix
+numux 'dev:*'              # all scripts matching dev:*
+numux 'npm:*:dev'          # explicit npm: prefix (same behavior)
+.fi
+.RE
+<!\-\- generated:script\-pattern\-rules \-\->
+.SH Script pattern rules
+.P
+\fBRecognition:\fR A process name is treated as a script reference when it:
+
+.RS 1
+.IP \(bu 2
+starts with \fBnpm:\fP (e\.g\. \fBnpm:dev:*\fP)
+.IP \(bu 2
+contains glob metacharacters (\fB*\fP, \fB?\fP, \fB[\fP)
+.IP \(bu 2
+contains a colon AND has no explicit \fBcommand\fP (e\.g\. \fBlint:eslint: {}\fP)
+
+.RE
+.P
+\fBGlob matching:\fR Patterns are matched against \fBpackage\.json\fP scripts using
+.br
+\fBBun\.Glob\fP\|\. The \fB*\fP wildcard does NOT match across \fB:\fP separators — \fBdev:*\fP
+.br
+matches \fBdev:web\fP but not \fBdev:web:hmr\fP\|\. Use \fBdev:*:*\fP for two levels deep\.
+.P
+\fBLeaf\-only (\fB^\fP):\fR Append \fB^\fP to skip scripts that are group runners —
+.br
+scripts that have sub\-scripts beneath them\. E\.g\. if \fBformat:check\fP has
+.br
+\fBformat:check:store\fP and \fBformat:check:odoo\fP below it, \fBformat:*^\fP excludes
+.br
+\fBformat:check\fP but keeps the leaf scripts\.
+.P
+\fBExtra args:\fR Anything after the first space in the pattern is forwarded
+.br
+as extra arguments to each matched command: \fBlint:* \-\-fix\fP → \fBbun run lint:js \-\- \-\-fix\fP\|\.
+.P
+\fBTemplate inheritance:\fR Config properties on a pattern entry (color, env,
+.br
+dependsOn, etc\.) are inherited by all expanded processes\. Color arrays are
+.br
+distributed round\-robin across matches\.
+.P
+\fBDisplay names:\fR The glob's literal prefix and suffix are stripped from
+.br
+matched script names: \fBdev:*\fP + \fBdev:web\fP → display name \fBweb\fP\|\.
+.SH Auto\-resolution
+.P
+When a process has no \fBcommand\fP and its name matches a \fBpackage\.json\fP script,
+.br
+the command is auto\-resolved to \fB<pm> run <name>\fP\|\. This works for:
+
+.RS 1
+.IP \(bu 2
+\fBtrue\fP or \fB{}\fP shorthand: \fBlint: true\fP → \fBbun run lint\fP
+.IP \(bu 2
+Objects without \fBcommand\fP: \fBtypecheck: { dependsOn: [&#39;db&#39;] }\fP → \fBbun run typecheck\fP
+
+.RE
+.SH npm: prefix
+.P
+Commands starting with \fBnpm:\fP are rewritten to use the detected package
+.br
+manager: \fBnpm:dev\fP → \fBbun run dev\fP (if bun is detected)\.
+<!\-\- /generated:script\-pattern\-rules \-\->
+
+.RS 2
+.nf
+numux 'lint:* \-\-fix'      # → bun run lint:js \-\-fix, bun run lint:ts \-\-fix
+.fi
+.RE
+.P
+In a config file, use the pattern as the process name:
+.RS 2
+.nf
+export default defineConfig({
+  processes: {
+    'dev:*': { color: ['green', 'cyan'] },
+    'lint:* \-\-fix': {},
+  },
+})
+.fi
+.RE
+.P
+Auto\-resolution example:
+.RS 2
+.nf
+export default defineConfig({
+  processes: {
+    lint: true,                       // → bun run lint
+    typecheck: { dependsOn: ['db'] }, // → bun run typecheck (with dependency)
+    db: 'docker compose up postgres', // explicit command, not resolved
+  },
+})
+.fi
+.RE
+.SS Options
+<!\-\- generated:options \-\->
+.TS
+tab(|) expand nowarn box;
+l l.
+T{
+Flag
+T}|T{
+Description
+T}
+=
+T{
+\fB\-s,\fP \fB\-\-sort\fP `<config
+T}|T{
+alphabetical
+T}
+_
+T{
+\fB\-w,\fP \fB\-\-workspace\fP \fB<script>\fP
+T}|T{
+Run a package\.json script across all workspaces
+T}
+_
+T{
+\fB\-n,\fP \fB\-\-name\fP \fB<name=command>\fP
+T}|T{
+Add a named process
+T}
+_
+T{
+\fB\-c,\fP \fB\-\-color\fP \fB<colors>\fP
+T}|T{
+Comma\-separated colors (hex or names: black, red, green, yellow, blue, magenta, cyan, white, gray, orange, purple)
+T}
+_
+T{
+\fB\-\-colors\fP
+T}|T{
+Auto\-assign colors to processes based on their name
+T}
+_
+T{
+\fB\-e,\fP \fB\-\-env\-file\fP `<path
+T}|T{
+false>`
+T}
+_
+T{
+\fB\-\-config\fP \fB<path>\fP
+T}|T{
+Config file path (default: auto\-detect)
+T}
+_
+T{
+\fB\-p,\fP \fB\-\-prefix\fP
+T}|T{
+Prefixed output mode (no TUI, for CI/scripts)
+T}
+_
+T{
+\fB\-\-only\fP \fB<a,b,\.\.\.>\fP
+T}|T{
+Only run these processes (+ their dependencies)
+T}
+_
+T{
+\fB\-\-exclude\fP \fB<a,b,\.\.\.>\fP
+T}|T{
+Exclude these processes
+T}
+_
+T{
+\fB\-\-kill\-others\fP
+T}|T{
+Kill all processes when any exits (regardless of exit code)
+T}
+_
+T{
+\fB\-\-kill\-others\-on\-fail\fP
+T}|T{
+Kill all processes when any exits with non\-zero code
+T}
+_
+T{
+\fB\-\-max\-restarts\fP \fB<n>\fP
+T}|T{
+Max auto\-restarts for crashed processes
+T}
+_
+T{
+\fB\-\-no\-watch\fP
+T}|T{
+Disable file watching even if config has watch patterns
+T}
+_
+T{
+\fB\-t,\fP \fB\-\-timestamps\fP \fB[<format>]\fP
+T}|T{
+Add timestamps to output (default HH:mm:ss, or pass a format string)
+T}
+_
+T{
+\fB\-\-log\-dir\fP \fB<path>\fP
+T}|T{
+Write per\-process logs to directory
+T}
+_
+T{
+\fB\-\-debug\fP
+T}|T{
+Enable debug logging to \.numux/debug\.log
+T}
+_
+T{
+\fB\-h,\fP \fB\-\-help\fP
+T}|T{
+Show this help
+T}
+_
+T{
+\fB\-v,\fP \fB\-\-version\fP
+T}|T{
+Show version
+T}
+.TE
+<!\-\- /generated:options \-\->
+
+.SS Prefix mode
+.P
+Use \fB\-\-prefix\fP (\fB\-p\fP) for CI or headless environments\. Output is printed with colored \fB[name]\fP prefixes instead of the TUI:
+.RS 2
+.nf
+numux \-\-prefix
+.fi
+.RE
+.P
+Auto\-exits when all processes finish\. Exit code 1 if any process failed\.
+.SH Logging
+.P
+numux writes per\-process log files (ANSI\-stripped) when \fB\-\-log\-dir\fP is set or \fBlogDir\fP is configured\. Each session creates a timestamped subdirectory with a \fBlatest\fP symlink pointing to the most recent run\.
+<!\-\- generated:logging\-usage \-\->
+.RS 2
+.nf
+numux logs                         # Print log directory path
+numux logs api                     # Pipe the api process log to stdout
+numux logs api | grep "ERROR"      # Search process logs
+numux logs api | tail \-f           # Follow process log output
+.fi
+.RE
+<!\-\- /generated:logging\-usage \-\->
+
+
+.SH Config reference
+.SS Global options
+.P
+Top\-level options apply to all processes (process\-level settings override):
+<!\-\- generated:config\-global \-\->
+.TS
+tab(|) expand nowarn box;
+l l l.
+T{
+Field
+T}|T{
+Type
+T}|T{
+Description
+T}
+=
+T{
+\fBcwd\fP
+T}|T{
+\fBstring\fP
+T}|T{
+Global working directory, inherited by all processes
+T}
+_
+T{
+\fBenv\fP
+T}|T{
+\fBRecord<string, string>\fP
+T}|T{
+Global env vars, merged into each process (process\-level overrides)
+T}
+_
+T{
+\fBenvFile\fP
+T}|T{
+\fBstring | string[] | false\fP
+T}|T{
+Global \.env file(s), inherited by processes without their own envFile; \fBfalse\fP disables
+T}
+_
+T{
+\fBshowCommand\fP
+T}|T{
+\fBboolean\fP
+T}|T{
+Global showCommand flag, inherited by all processes
+T}
+_
+T{
+\fBmaxRestarts\fP
+T}|T{
+\fBnumber\fP
+T}|T{
+Global restart limit, inherited by all processes (only restarts on non\-zero exit)
+T}
+_
+T{
+\fBreadyTimeout\fP
+T}|T{
+\fBnumber\fP
+T}|T{
+Global ready timeout (ms), inherited by all processes
+T}
+_
+T{
+\fBstopSignal\fP
+T}|T{
+\fB&#39;SIGTERM&#39; | &#39;SIGINT&#39; | &#39;SIGHUP&#39;\fP
+T}|T{
+Global stop signal, inherited by all processes
+T}
+_
+T{
+\fBerrorMatcher\fP
+T}|T{
+\fBboolean | string\fP
+T}|T{
+Global error matcher, inherited by all processes\. \fBtrue\fP = detect ANSI red output, string = regex
+T}
+_
+T{
+\fBwatch\fP
+T}|T{
+\fBstring | string[]\fP
+T}|T{
+Global watch patterns, inherited by processes without their own watch
+T}
+_
+T{
+\fBsort\fP
+T}|T{
+\fB&#39;config&#39; | &#39;alphabetical&#39; | &#39;topological&#39;\fP
+T}|T{
+Tab display order\. \fB&#39;config&#39;\fP preserves definition order (package\.json script order for wildcards), \fB&#39;alphabetical&#39;\fP sorts by process name, \fB&#39;topological&#39;\fP sorts by dependency tiers\.
+T}
+_
+T{
+\fBprefix\fP
+T}|T{
+\fBboolean\fP
+T}|T{
+Use prefixed output mode instead of TUI (for CI/scripts)
+T}
+_
+T{
+\fBtimestamps\fP
+T}|T{
+\fBboolean | string\fP
+T}|T{
+Add timestamps to output lines\. \fBtrue\fP uses default \fBHH:mm:ss\fP format, or pass a format string (e\.g\. \fB&quot;HH:mm:ss\.SSS&quot;\fP)
+T}
+_
+T{
+\fBkillOthers\fP
+T}|T{
+\fBboolean\fP
+T}|T{
+Kill all processes when any one exits (regardless of exit code)
+T}
+_
+T{
+\fBkillOthersOnFail\fP
+T}|T{
+\fBboolean\fP
+T}|T{
+Kill all processes when any one exits with a non\-zero exit code
+T}
+_
+T{
+\fBnoWatch\fP
+T}|T{
+\fBboolean\fP
+T}|T{
+Disable file watching even if processes have watch patterns
+T}
+_
+T{
+\fBlogDir\fP
+T}|T{
+\fBstring\fP
+T}|T{
+Directory to write per\-process log files
+T}
+.TE
+<!\-\- /generated:config\-global \-\->
+
+.RS 2
+.nf
+export default defineConfig({
+  cwd: '\./packages/backend',
+  env: { NODE_ENV: 'development' },
+  envFile: '\.env',
+  processes: {
+    api: { command: 'node server\.js' },           // inherits cwd, env, envFile
+    web: { command: 'vite', cwd: '\./packages/web' }, // overrides cwd
+  },
+})
+.fi
+.RE
+.SS Process options
+.P
+Each process accepts:
+<!\-\- generated:config\-process \-\->
+.TS
+tab(|) expand nowarn box;
+l l l l.
+T{
+Field
+T}|T{
+Type
+T}|T{
+Default
+T}|T{
+Description
+T}
+=
+T{
+\fBcommand\fP
+T}|T{
+\fBstring\fP
+T}|T{
+\fIrequired\fR
+T}|T{
+Shell command to run\. Supports \fB$dep\.group\fP references from dependency capture groups
+T}
+_
+T{
+\fBcwd\fP
+T}|T{
+\fBstring\fP
+T}|T{
+—
+T}|T{
+Working directory for the process
+T}
+_
+T{
+\fBenv\fP
+T}|T{
+\fBRecord<string, string>\fP
+T}|T{
+—
+T}|T{
+Extra environment variables\. Values support \fB$dep\.group\fP references from dependency capture groups\.
+T}
+_
+T{
+\fBenvFile\fP
+T}|T{
+\fBstring | string[] | false\fP
+T}|T{
+—
+T}|T{
+\|\.env file path(s) to load, or \fBfalse\fP to disable
+T}
+_
+T{
+\fBdependsOn\fP
+T}|T{
+\fBstring | string[]\fP
+T}|T{
+—
+T}|T{
+Processes that must be ready before this one starts
+T}
+_
+T{
+\fBreadyPattern\fP
+T}|T{
+\fBstring | RegExp\fP
+T}|T{
+—
+T}|T{
+Regex matched against stdout to signal readiness\. Use \fBRegExp\fP to capture groups for \fB$dep\.group\fP expansion
+T}
+_
+T{
+\fBmaxRestarts\fP
+T}|T{
+\fBnumber\fP
+T}|T{
+\fB0\fP
+T}|T{
+Limit auto\-restart attempts (only restarts on non\-zero exit)
+T}
+_
+T{
+\fBreadyTimeout\fP
+T}|T{
+\fBnumber\fP
+T}|T{
+—
+T}|T{
+Milliseconds to wait for readyPattern before failing
+T}
+_
+T{
+\fBdelay\fP
+T}|T{
+\fBnumber\fP
+T}|T{
+—
+T}|T{
+Milliseconds to wait before starting the process
+T}
+_
+T{
+\fBcondition\fP
+T}|T{
+\fBstring\fP
+T}|T{
+—
+T}|T{
+Env var name (prefix with \fB!\fP to negate); process skipped if condition is falsy
+T}
+_
+T{
+\fBplatform\fP
+T}|T{
+\fBstring | string[]\fP
+T}|T{
+—
+T}|T{
+OS(es) this process runs on (e\.g\. \fB&#39;darwin&#39;\fP, \fB&#39;linux&#39;\fP)\. Non\-matching processes are removed, their dependents still start
+T}
+_
+T{
+\fBstopSignal\fP
+T}|T{
+\fB&#39;SIGTERM&#39; | &#39;SIGINT&#39; | &#39;SIGHUP&#39;\fP
+T}|T{
+\fB&#39;SIGTERM&#39;\fP
+T}|T{
+Signal for graceful stop
+T}
+_
+T{
+\fBcolor\fP
+T}|T{
+\fBstring | string[]\fP
+T}|T{
+—
+T}|T{
+Hex color (e\.g\. \fB&quot;#ff6600&quot;\fP) or color name\. Array for round\-robin in script patterns
+T}
+_
+T{
+\fBwatch\fP
+T}|T{
+\fBstring | string[]\fP
+T}|T{
+—
+T}|T{
+Glob patterns — restart process when matching files change
+T}
+_
+T{
+\fBinteractive\fP
+T}|T{
+\fBboolean\fP
+T}|T{
+\fBfalse\fP
+T}|T{
+When true, keyboard input is forwarded to the process
+T}
+_
+T{
+\fBoptional\fP
+T}|T{
+\fBboolean\fP
+T}|T{
+—
+T}|T{
+Process is visible but not started automatically\. Use Alt+S to start manually
+T}
+_
+T{
+\fBerrorMatcher\fP
+T}|T{
+\fBboolean | string\fP
+T}|T{
+—
+T}|T{
+\fBtrue\fP = detect ANSI red output, string = regex pattern
+T}
+_
+T{
+\fBworkspaces\fP
+T}|T{
+\fBboolean | string | string[]\fP
+T}|T{
+—
+T}|T{
+Run command in monorepo workspaces\. \fBtrue\fP = all workspaces, string = specific workspace by name/path, string[] = multiple workspaces
+T}
+_
+T{
+\fBshowCommand\fP
+T}|T{
+\fBboolean\fP
+T}|T{
+\fBtrue\fP
+T}|T{
+Print the command being run as the first line of output
+T}
+.TE
+<!\-\- /generated:config\-process \-\->
+
+.SS Workspace expansion
+.P
+Use \fBworkspaces\fP on a process to expand it into per\-workspace processes\. Reads the \fBworkspaces\fP field from your root \fBpackage\.json\fP\|\.
+.RS 2
+.nf
+export default defineConfig({
+  processes: {
+    // All workspaces — filters by script availability for PM run commands
+    lint: { command: 'npm run lint', workspaces: true },
+
+    // Specific workspace by package name
+    validate: { command: 'npm run validate', workspaces: '@repo/image\-worker' },
+
+    // Multiple specific workspaces
+    dev: { command: 'npm run dev', workspaces: ['@repo/api', '@repo/web'] },
+  },
+})
+.fi
+.RE
+.P
+Each entry expands into \fB{name}:{wsName}\fP processes (e\.g\. \fBlint:api\fP, \fBlint:web\fP) with \fBcwd\fP set to the workspace directory\. All other config (env, dependsOn, color, etc\.) is inherited from the template\.
+.P
+When \fBworkspaces: true\fP is used with a PM run command (\fBnpm run lint\fP), only workspaces that have the matching script are included\. Raw commands (\fBeslint \.\fP) run in all workspaces\.
+.P
+String values resolve by package name first (with or without scope), then fall back to relative path\. Cannot be combined with \fBcwd\fP\|\.
+.SS File watching
+.P
+Use \fBwatch\fP to automatically restart a process when source files change:
+.RS 2
+.nf
+export default defineConfig({
+  processes: {
+    api: {
+      command: 'node server\.js',
+      watch: 'src/**/*\.ts',
+    },
+    styles: {
+      command: 'sass \-\-watch src:dist',
+      watch: ['src/**/*\.scss', 'src/**/*\.css'],
+    },
+  },
+})
+.fi
+.RE
+.P
+Patterns are matched relative to the process's \fBcwd\fP (or the project root)\. Changes in \fBnode_modules\fP and \fB\|\.git\fP are always ignored\. Rapid file changes are debounced (300ms) to avoid restart storms\.
+.P
+A watched process is only restarted if it's currently running, ready, or failed — manually stopped processes are not affected\.
+.SS Environment variable interpolation
+.P
+Config values support \fB${VAR}\fP syntax for environment variable substitution:
+.RS 2
+.nf
+export default defineConfig({
+  processes: {
+    api: {
+      command: 'node server\.js \-\-port ${PORT:\-3000}',
+      env: {
+        DATABASE_URL: '${DATABASE_URL:?DATABASE_URL must be set}',
+      },
+    },
+  },
+})
+.fi
+.RE
+.TS
+tab(|) expand nowarn box;
+l l.
+T{
+Syntax
+T}|T{
+Behavior
+T}
+=
+T{
+\fB${VAR}\fP
+T}|T{
+Value of \fBVAR\fP, or empty string if unset
+T}
+_
+T{
+\fB${VAR:\-default}\fP
+T}|T{
+Value of \fBVAR\fP, or \fBdefault\fP if unset
+T}
+_
+T{
+\fB${VAR:?error}\fP
+T}|T{
+Value of \fBVAR\fP, or error with message if unset
+T}
+.TE
+.P
+Interpolation applies to all string values in the config (command, cwd, env, envFile, readyPattern, etc\.)\.
+.SS Conditional processes
+.P
+Use \fBcondition\fP to run a process only when an environment variable is set:
+.RS 2
+.nf
+export default defineConfig({
+  processes: {
+    seed: {
+      command: 'bun run seed',
+      condition: 'SEED_DB',    // only runs when SEED_DB is set and truthy
+    },
+    storybook: {
+      command: 'bun run storybook',
+      condition: '!CI',         // skipped in CI environments
+    },
+  },
+})
+.fi
+.RE
+.P
+Falsy values: unset, empty string, \fB&quot;0&quot;\fP, \fB&quot;false&quot;\fP, \fB&quot;no&quot;\fP, \fB&quot;off&quot;\fP (case\-insensitive)\. If a conditional process is skipped, its dependents are also skipped\.
+.SS Optional processes
+.P
+Use \fBoptional\fP for tools you want visible in tabs but not auto\-started (e\.g\. Prisma Studio, debug servers):
+.RS 2
+.nf
+export default defineConfig({
+  processes: {
+    app: { command: 'bun run dev' },
+    studio: {
+      command: 'bunx prisma studio',
+      optional: true,  // shows as stopped tab, start with Alt+S
+    },
+  },
+})
+.fi
+.RE
+.P
+Unlike \fBcondition\fP, optional processes don't cascade — their dependents still start normally\.
+.SS Dependency orchestration
+.P
+Each process starts as soon as its declared \fBdependsOn\fP dependencies are ready — it does not wait for unrelated processes\. If a process fails, its dependents are skipped\.
+.P
+A process becomes \fBready\fR when:
+
+.RS 1
+.IP \(bu 2
+\fBHas \fBreadyPattern\fP\fR — the pattern matches in stdout (long\-running server)
+.IP \(bu 2
+\fBNo \fBreadyPattern\fP\fR — exits with code 0 (one\-shot task)
+
+.RE
+.P
+Processes that crash (non\-zero exit) can be auto\-restarted by setting \fBmaxRestarts\fP (default: \fB0\fP)\. Restarts use exponential backoff (1s–30s), which resets after 10s of uptime\.
+.SS Dependency output capture
+.P
+When \fBreadyPattern\fP is a \fBRegExp\fP (not a string), capture groups are extracted on match and expanded into dependent process \fBcommand\fP and \fBenv\fP values using \fB$process\.group\fP syntax:
+.RS 2
+.nf
+export default defineConfig({
+  processes: {
+    db: {
+      command: 'docker compose up postgres',
+      readyPattern: /ready to accept connections on port (?<port>\\d+)/,
+    },
+    api: {
+      command: 'node server\.js \-\-db\-port $db\.port',
+      dependsOn: ['db'],
+      env: { DB_PORT: '$db\.port' },
+    },
+  },
+})
+.fi
+.RE
+.P
+Both named (\fB$db\.port\fP) and positional (\fB$db\.1\fP) references work\. Named groups also populate positional slots, so \fB$db\.port\fP and \fB$db\.1\fP both resolve to the same value above\.
+.P
+Unmatched references are left as\-is (the shell will expand \fB$db\fP as empty + \fB\|\.port\fP literal, making the issue visible)\. String \fBreadyPattern\fP values work as before — readiness detection only, no capture extraction\.
+.SH Keybindings
+.P
+Keybindings are shown in the status bar at the bottom of the app\. Panes are readonly by default — keyboard input is not forwarded to processes\. Set \fBinteractive: true\fP on processes that need stdin (REPLs, shells, etc\.)\.
+<!\-\- generated:keybindings \-\->
+.TS
+tab(|) expand nowarn box;
+l l.
+T{
+Key
+T}|T{
+Action
+T}
+=
+T{
+\fB←\fP/\fB→\fP or \fB1\fP\-\fB9\fP
+T}|T{
+Tabs
+T}
+_
+T{
+\fBG/Shift+G\fP
+T}|T{
+Top/bottom
+T}
+_
+T{
+\fBR\fP
+T}|T{
+Restart
+T}
+_
+T{
+\fBS\fP
+T}|T{
+Stop/start
+T}
+_
+T{
+\fBF\fP
+T}|T{
+Search
+T}
+_
+T{
+\fBY\fP
+T}|T{
+Copy all
+T}
+_
+T{
+\fBL\fP
+T}|T{
+Clear
+T}
+_
+T{
+\fBT\fP
+T}|T{
+Timestamps
+T}
+_
+T{
+\fBO\fP
+T}|T{
+Open logs
+T}
+_
+T{
+\fBCtrl+Click\fP
+T}|T{
+Open link
+T}
+_
+T{
+\fBCtrl+C\fP
+T}|T{
+Quit
+T}
+.TE
+<!\-\- /generated:keybindings \-\->
+
+.P
+Search mode (after pressing \fBF\fP):
+.TS
+tab(|) expand nowarn box;
+l l.
+T{
+Key
+T}|T{
+Action
+T}
+=
+T{
+\fBTab\fP
+T}|T{
+Toggle between single\-pane and all\-process search
+T}
+_
+T{
+\fBEnter\fP/\fBShift+Enter\fP
+T}|T{
+Next/previous match
+T}
+_
+T{
+\fBEsc\fP
+T}|T{
+Exit search
+T}
+_
+T{
+\fBPageUp\fP/\fBPageDown\fP
+T}|T{
+Scroll by page
+T}
+.TE
+.SH Tab icons
+<!\-\- generated:tab\-icons \-\->
+.TS
+tab(|) expand nowarn box;
+l l.
+T{
+Icon
+T}|T{
+Status
+T}
+=
+T{
+○
+T}|T{
+Pending
+T}
+_
+T{
+◐
+T}|T{
+Starting
+T}
+_
+T{
+◉
+T}|T{
+Running
+T}
+_
+T{
+●
+T}|T{
+Ready
+T}
+_
+T{
+◑
+T}|T{
+Stopping
+T}
+_
+T{
+■
+T}|T{
+Stopped
+T}
+_
+T{
+✓
+T}|T{
+Finished
+T}
+_
+T{
+✖
+T}|T{
+Failed
+T}
+_
+T{
+⊘
+T}|T{
+Skipped
+T}
+.TE
+<!\-\- /generated:tab\-icons \-\->
+
+.SH Dependencies
+.SS ghostty\-opentui
+.P
+Despite the name, 
+.UR https://github.com/remorses/ghostty-opentui
+.I `ghostty-opentui`
+.UE
+is \fBnot\fR a compatibility layer for the 
+.UR https://ghostty.org
+.I Ghostty
+.UE
+terminal\. It uses Ghostty's Zig\-based VT parser as the ANSI terminal emulation engine for OpenTUI's terminal renderable\. It works in any terminal emulator (iTerm, Kitty, Alacritty, WezTerm, etc\.) and adds ~8MB to install size due to native binaries\.
+.SH License
+.P
+MIT
+