terminal¶

The Herdr backend supports only the latest Herdr CLI and server. See the Herdr CLI reference for current command syntax.

Usage¶

terminal [OPTIONS] COMMAND [ARGS]...

Commands Overview¶

Command	Description
`run`	Launch selected layouts from a layout file or generated test layout
`run-all`	Dynamically work through every tab in one merged run
`attach`	Attach to an existing session, window/tab, or pane
`kill`	Kill a session target
`export`	Export running tmux sessions into a layout file
`trace`	Trace a tmux session until a strict stop condition is met
`summary`	Print running session summaries or one session's details
`create-from-function`	Build and launch a multiprocess layout from a script function
`balance-load`	Re-split a layout file by tab count or weight
`create-template`	Create a starter layout file in the current directory
`summarize`	Print layout counts and per-layout tab totals

Hidden one-letter aliases exist, but this page uses canonical command names.

Common Layout Source Rules¶

Without LAYOUTS_FILE or --test-layout, run and run-all combine named layouts from ~/dotfiles/stackops/config/layouts.json and PWD/.stackops/config/layout.json, including each file that exists, then open a layout picker. PWD is the current working directory. Cancelling the picker aborts the command.
The default picker labels entries global:name or local:name and previews their source file paths. Layout and session names remain unchanged.
An explicit LAYOUTS_FILE loads layouts only from the supplied file.
For run, an explicit --choose-layouts or --choose-tabs selector uses that selection without opening an additional layout picker.
run and run-all also support --test-layout, which generates a built-in finite layout set for experimentation and cannot be combined with LAYOUTS_FILE.
--choose-layouts "" opens interactive layout selection.
Named layout selectors accept an unambiguous name or global:name / local:name. A name shared by both sources requires the qualified form.
--choose-tabs "" opens interactive tab selection.
Tab selectors accept tabName or layoutName::tabName. When both sources share a layout name, qualify it as global:layoutName::tabName or local:layoutName::tabName; an ambiguous layout name is rejected. Bare tab names match across selected layouts.

run¶

Launch selected layouts from an explicit file or the default layout files.

terminal run [OPTIONS] [LAYOUTS_FILE]

Argument / Option	Short	Description
`LAYOUTS_FILE`	-	Optional layout file path; omit to select from the combined default files
`--test-layout`	`-L`	Use the generated mock layout instead of reading a file
`--choose-layouts`	`-l`	Comma-separated layout names, or `""` for interactive selection
`--choose-tabs`	`-t`	Comma-separated tab names, or `""` for interactive selection across all layouts
`--sleep-inbetween`	`-S`	Delay between launching layouts
`--parallel-layouts`	`-p`	Maximum number of layouts to launch per monitored batch
`--max-tabs-per-layout`	`-T`	Sanity limit for tabs inside a single selected layout
`--max-parallel-layouts`	`-P`	Sanity limit for total parallel layouts
`--backend`	`-b`	`tmux`/`t`, `herdr`/`h`, `aoe`/`a`, or `auto`
`--on-conflict`	`-c`	`error`, `restart`, `rename`, `mergeOverwrite`, or `mergeSkip`
`--exit`	`-e`	`backToShell`, `terminate`, or `killWindow` after each command exits
`--monitor`	`-m`	Monitor launched sessions for completion
`--kill-upon-completion`	`-k`	Kill sessions after monitored completion
`--substitute-home`	`-H`	Expand `~` and `$HOME` inside the selected layout tabs

Examples:

# Choose layouts from the global file and PWD/.stackops/config/layout.json when present
terminal run

# Run unambiguous named layouts from the combined default files without prompting
terminal run --choose-layouts "dev,build"

# Select the local dev layout when both sources define dev
terminal run --choose-layouts "local:dev"

# Select a tab from the local dev layout
terminal run --choose-tabs "local:dev::server"

# Run only selected layouts from an explicit file
terminal run layouts.json --choose-layouts "dev,build"

# Run a generated test layout
terminal run --test-layout --parallel-layouts 2 --monitor

# Select tabs by name or layout-qualified name
terminal run layouts.json --choose-tabs "server,build::tests"

# Restart matching sessions before relaunching
terminal run layouts.json --on-conflict restart

# Launch selected layouts through Herdr
terminal run layouts.json --backend herdr

# Launch selected layout tabs through Agent of Empires
terminal run layout.json --backend aoe

run-all¶

Merge every tab from the selected layouts into one paced run. An explicit file uses all its layouts; omitting the file opens a picker for the combined default files. --max-parallel-tabs is required in both cases.

terminal run-all [OPTIONS] [LAYOUTS_FILE]

Argument / Option	Short	Description
`LAYOUTS_FILE`	-	Optional file whose layouts all run; omit to choose layouts from the combined default files
`--test-layout`	`-T`	Use the generated mock layout instead of reading a file
`--max-parallel-tabs`	`-t`	Required cap for concurrently active tabs
`--poll-seconds`	`-p`	Polling interval for finished-tab detection
`--kill-finished-tabs`	`-k`	Close each tab as soon as its command finishes
`--on-conflict`	`-c`	`error`, `restart`, or `rename`; merge policies are rejected
`--substitute-home`	`-H`	Expand `~` and `$HOME` inside selected tabs

Examples:

# Choose layouts from the combined default files and keep at most eight tabs active
terminal run-all --max-parallel-tabs 8

# Keep at most eight tabs active while working through the whole file
terminal run-all layouts.json --max-parallel-tabs 8

# Use the generated test layout and close finished tabs as work drains
terminal run-all --test-layout --max-parallel-tabs 6 --kill-finished-tabs

attach¶

Attach to a session target.

terminal attach [OPTIONS] [NAME]

Option	Short	Description
`NAME`	-	Session name to attach to; omit for interactive selection
`--new-session`	`-n`	Create a new session instead of attaching
`--kill-all`	`-k`	Kill all existing sessions before creating a new one
`--first`	`-f`	Attach to the first available tmux session without prompting
`--window`	`-w`	Choose a window/tab or pane target instead of only sessions
`--backend`	`-b`	`tmux`, `herdr`, `aoe`, or `auto`

Example:

# Attach to the first tmux session without opening the chooser
terminal attach --first

# Choose a pane or tab interactively
terminal attach --window

# Attach to a Herdr session
terminal attach --backend herdr

# Attach to an Agent of Empires session
terminal attach --backend aoe

kill¶

Kill a session target.

terminal kill [OPTIONS] [NAME]

Option	Short	Description
`NAME`	-	Session name to kill; omit for interactive selection
`--all`	`-a`	Kill all sessions; with `--idle`, inspect all sessions for idle panes/windows
`--idle`	`-i`	Kill idle-shell panes/windows in `NAME` or a chosen session; combine with `--all` to inspect all sessions
`--window`	`-w`	Include sessions, windows/tabs, and panes in the chooser
`--delete`	`-D`	Delete stopped Herdr session records instead of killing running sessions
`--backend`	`-b`	`tmux`, `herdr`, `aoe`, or `auto`

Example:

# Choose an exact pane or tab to kill
terminal kill --window

# Kill idle-shell panes/windows across every tmux session
terminal kill --idle --all

# Stop an Agent of Empires session
terminal kill --backend aoe

export¶

Export running tmux sessions or Herdr workspaces into a layout file that terminal run can launch.

terminal export [OPTIONS]

Option	Short	Description
`--sessions`	`-s`	Comma-separated tmux session names or Herdr workspace labels/IDs; omit for interactive multi-select
`--all`	`-A`	Export all running backend sessions/workspaces without prompting
`--output-path`	`-o`	Output layout file; defaults to `./tmux_export_layout.json`
`--overwrite`	`-w`	Replace the output file if it already exists
`--merge`	`-m`	Merge exported sessions into an existing layout file by `layoutName`
`--backend`	`-b`	`tmux`/`t` or `herdr`/`h`; defaults to `tmux`
`--command-source`	`-c`	`shell`, `current-command`, or `start-command`; defaults to `shell`

Examples:

# Choose tmux sessions interactively, with previews
terminal export

# Export specific sessions into a runnable layout file
terminal export --sessions "dev,build" --output-path exported_layout.json

# Export every running tmux session, then replay it with run
terminal export --all --output-path exported_layout.json --overwrite
terminal run exported_layout.json

# Export Herdr workspaces, then replay them with run
terminal export --backend herdr --all --output-path exported_layout.json --overwrite
terminal run exported_layout.json --backend herdr

trace¶

Trace a tmux session, Herdr workspace, or Agent of Empires session until every observable target matches a strict stop criterion.

terminal trace [SESSION_NAME] [OPTIONS]

Option	Short	Description
`SESSION_NAME`	-	tmux session name, Herdr workspace label/id, or AoE session title/id to trace; omit when using `--interactive`
`--backend`	`-b`	Backend to trace; `tmux`/`t`, `herdr`/`h`, or `aoe`/`a`/`e`
`--interactive`	`-i`	Choose an existing backend session/workspace interactively
`--every`	`-e`	Polling interval in seconds
`--until`	`-u`	`idle-shell`, `all-exited`, `exit-code`, or `session-missing`
`--exit-code`	`-c`	Required exit code when `--until exit-code` is selected

With --backend herdr, tracing supports idle-shell and session-missing. Herdr's API does not expose process exit status, so all-exited and exit-code are rejected. Herdr agent states idle and done both count as ready for input; done indicates an unseen completion.

Examples:

# Choose an existing session interactively
terminal trace --interactive

# Wait until every pane returns to an idle shell
terminal trace build-session

# Wait until every pane has exited
terminal trace build-session --every 5 --until all-exited

# Trace a Herdr workspace by label
terminal trace build-workspace --backend herdr

# Trace an Agent of Empires session by title
terminal trace build-session --backend aoe

# Require successful exit codes from every pane
terminal trace build-session --until exit-code --exit-code 0

summary¶

Print running terminal session summaries, or show details for one chosen session.

terminal summary [OPTIONS]

Option	Short	Description
`--backend`	`-b`	Backend to summarize; `tmux`/`t`, `herdr`/`h`, `aoe`/`a`, or `auto`
`--session`	`-s`	Show details for one tmux session, Herdr workspace, or AoE session by name
`--choose-session`	`-c`	Choose one tmux session, Herdr workspace, or AoE session interactively and show details

Examples:

# Show the aggregate tmux session table
terminal summary

# Show windows and panes for one named session
terminal summary --session build-session

# Choose a session interactively, with preview, then show details
terminal summary --choose-session

# Show Herdr workspaces
terminal summary --backend herdr

# Show Agent of Empires sessions
terminal summary --backend aoe

create-from-function¶

terminal create-from-function [OPTIONS]

Option	Short	Description
`--num-process`	`-n`	Required number of parallel processes
`--path`	`-p`	Script file or directory to search
`--function`	`-f`	Function name to run

Each generated tab runs:

uv run python -m fire <file> <function> --idx=<n> --idx_max=<num_process>

Example:

terminal create-from-function --num-process 4 --path ./my_script.py --function process_data

balance-load¶

Adjust a layout file to limit tabs per layout or total layout weight.

terminal balance-load LAYOUT_PATH [OPTIONS]

Option	Short	Description
`--max-threshold`	`-m`	Required threshold value
`--threshold-type`	`-t`	`number`/`n` or `weight`/`w`
`--breaking-method`	`-b`	`moreLayouts`/`ml` or `combineTabs`/`ct`
`--output-path`	`-o`	Output path for the rewritten file

If --output-path is omitted, StackOps writes <stem>_adjusted_<max>_<threshold>_<method>.json beside the source file.

create-template¶

Create a starter layout file in the current directory.

terminal create-template [NAME] [OPTIONS]

Option	Short	Description
`NAME`	-	Optional output filename stem; defaults to `layout.json`
`--num-tabs`	`-t`	Number of tabs to include

Current behavior:

The template uses the current directory to build startDir.
The default tab command is bash on non-Windows systems and powershell on Windows.
Existing files are not overwritten.

summarize¶

Print layout counts and per-layout tab totals.

terminal summarize LAYOUT_PATH [OPTIONS]

Current behavior:

Prints the file path, version, total layout count, total tab count, average tabs per layout, and min/max tab counts.
Accepts the current wrapped layout-file shape with a top-level layouts array.
Use --vocabulary herdr to summarize the same layout file with Herdr workspace terminology.

Layout File Format¶

Current layout files use the LayoutsFile wrapper. The important keys are layouts, layoutName, layoutTabs, tabName, startDir, and command.

{
  "$schema": "https://raw.githubusercontent.com/thisismygitrepo/stackops/refs/heads/main/src/stackops/utils/schemas/layouts/layout.schema.json",
  "version": "0.1",
  "layouts": [
    {
      "layoutName": "Development",
      "layoutTabs": [
        {
          "tabName": "editor",
          "startDir": "~/projects/myapp",
          "command": "hx ."
        },
        {
          "tabName": "server",
          "startDir": "~/projects/myapp",
          "command": "python -m http.server 8000"
        }
      ]
    }
  ]
}

Older examples that use tabs or cwd are stale. The current schema uses layoutTabs and startDir.

Backend Notes¶

trace supports tmux sessions, Herdr workspaces, and Agent of Empires sessions.