CLI Commands and Flags

This page is full command reference. It is intentionally dense.

Command forms

broski --workspace <path> <command>
broski <task> [task-args...] [flags]
broski run <task> [task-args...] [flags]
broski list
broski graph <task> --format text|dot
broski doctor [--repair|--no-repair]
broski cache prune --max-size <MB>
broski tui <task> [--theme <name>]
broski history [<task>] [--limit <N>]

Resolution rules

1. Subcommands win over task names.
2. Use broski run <task> when you want explicit task resolution.
3. Reserved names are blocked as task names: run, list, graph, doctor, cache, help, version, tui, history.

Run behavior flags

These flags apply to broski <task> and broski run <task>.

Flag	Default	Effect	Notes
--dry-run	off	Compute graph and show what would run, without execution.	Useful for CI validation and migration checks.
--explain	off	Print cache miss reasons per task.	Reasons are based on manifest deltas (input, env, run, outputs, etc.).
--force	off	Bypass cache read and execute tasks.	Explain output shows cache bypass: --force supplied.
--no-cache	off	Do not read from cache and do not write cache artifacts.	Explain output shows cache bypass: --no-cache supplied.
--watch	off	Re-run target graph on input changes.	See Watch Mode.
--force-isolation	off	Force strict isolation for graph tasks.	Not supported for interactive tasks.
--jobs <n>	auto	Override worker concurrency.	Explicit run supports --jobs <n>. Implicit run supports --jobs=<n>.
--tui	off	Render this run through the live TUI dashboard instead of the spinner output.	Mutually exclusive with --dry-run, --explain, and --watch.
--theme <name>	default	Dashboard color palette (default, dark, light, high-contrast/hc, auto).	Also honored via BROSKI_THEME. auto queries the terminal background via OSC 11. Only meaningful with --tui or broski tui.

Global flags

Flag	Effect
--workspace <path>	Resolve broskifile, cache state, runtime lock, and paths relative to this workspace root.

Example:

broski --workspace /path/to/repo run ci --explain

Important parsing detail

For implicit invocation (broski setup), Broski consumes engine flags itself:

broski setup --explain --dry-run

To pass a literal flag to the underlying task command, use --:

broski setup -- --explain

Subcommands

broski list

List tasks and aliases from the loaded broskifile.

• @private tasks are hidden from default listing.
• Task descriptions are surfaced from preceding comments in DSL docs.

broski run <task> and broski <task>

Execute a target and its dependency graph.

• Graph tasks: staged, fingerprinted, cache-aware.
• Interactive tasks: no cache, no staging, TTY inherited.

Examples:

broski run ci --explain
broski ci --jobs=8
broski run build api release --force-isolation
broski test -- --grep slow

broski graph <task> --format text|dot

Show dependency graph for a target.

broski graph ci --format text
broski graph ci --format dot > graph.dot

Use dot output for Graphviz rendering.

broski doctor

Check runtime state and lock health under .broski/runtime.

Mode	Behavior
default (doctor)	Reports and repairs stale runtime state.
--no-repair	Report-only mode, no mutation.
--repair	Explicit repair mode.

When an active lock is live, doctor refuses destructive cleanup.

broski cache prune --max-size <MB>

Prune local cache store to size budget.

• Unit is megabytes.
• Example:

broski cache prune --max-size 512

Output reports objects pruned, bytes freed, and remaining size.

broski tui [task] and broski run <task> --tui

Render the run through a live ratatui-based dashboard:

• DAG view with per-task state, inline (cached) / (skipped) / (dry-run) / (failed) tags, and ETA badges (sourced from the most recent successful execution).
• Scrollable log tail (mouse wheel + PageUp/Down + Shift-↑/↓ + Shift-Home/End; auto-follows the tail and locks when you scroll up).
• Summary bar with aggregate remaining-time and overall status.
• Two-stage Ctrl-C: first press requests a soft cancel; a second press within two seconds escalates to a hard cancel (SIGTERM to all child PIDs) and exits.
• --explain is supported: per-task miss reasons land inline on each DAG line and at the top of the selected task's log pane.
• Interactive tasks (@mode interactive) automatically suspend the dashboard, hand the real TTY to the child via Stdio::inherit, and resume the dashboard when the child exits.

Dashboard key map

Key	Effect
↑ / ↓ / j / k	Move selection cursor in the DAG pane.
Home / g	Jump to first task.
End / G	Jump to last task.
PageUp / PageDown	Scroll log pane 10 lines.
Shift-↑ / Shift-↓	Scroll log pane 1 line.
Shift-Home / Shift-End	Jump log pane to top / tail.
Mouse wheel	Scroll log pane 3 lines per notch.
x	Force-rerun the selected task only (deps stay cached). Available after run finishes.
X	Force-rerun the entire original target (--force for all tasks). Available after run finishes.
c	Clear logs for the selected task.
r	Redraw.
Ctrl-C	Soft cancel (first press); hard cancel + exit (second press within 2 s).
q / Esc	Quit without cancelling.

Launcher mode

Run broski tui with no task to enter the interactive launcher. Side-by-side layout: tasks on the left, stats / slash-command suggestions on the right.

• Filterable task list (type-ahead substring match, case-insensitive).
• Free-form input box with a real blinking cursor; -- in the input forwards trailing tokens as task passthrough args.
• Tab completes the input from the highlighted task; Esc/Ctrl-U clears.
• Enter runs the typed target — or the highlighted match if the input is a partial substring — then pops back to the launcher with a status banner.
• q / Ctrl-C exit only when the input is empty.

Slash commands

Type / in the input box to flip into a command palette. Tab completes to the canonical form, Enter dispatches.

Command	Effect
/help	Show key map + command catalog (alias /h, /?).
/theme <name>	Switch theme live: default, dark, light, high-contrast, auto.
/about	Show broski version (alias /version).
/clear	Wipe session history and reset counters.
/refresh	Reload broskifile and refresh stats (alias /reload).
/cache prune <MB>	Prune the cache to a size budget; report bytes freed.
/quit	Exit the launcher (aliases /q, /exit).

Stats panel

In Filter mode, the right column shows live info in stacked cards:

• Workspace — path, version, git rev, theme (with auto → dark resolution when applicable).
• Cache — object count and total size.
• Session — total runs · ✓✗⊘ counters · accumulated wall-clock.
• Task detail — when a task is highlighted: description, deps, @in/@out counts, last successful run.
• Recent runs — last few completed runs.

Auto theme

--theme auto queries the terminal's background via OSC 11 and picks Dark or Light. Falls back to Default when the terminal doesn't respond.

Theme selection:

broski tui                                 # launcher
broski tui ci --theme dark                 # straight to a target
broski run ci --tui --theme high-contrast
BROSKI_THEME=light broski tui ci

The dashboard is mutually exclusive with --dry-run, --explain, and --watch because those flags expect direct stdout output.

broski history [<task>] [--limit <N>]

Read-only summary of recent successful runs from the artifact store.

• broski history lists the most recent run per task (newest first), with relative time and duration.
• broski history <task> --limit N lists the last N runs for a single task with absolute time, duration, and short fingerprint.

broski history
broski history ci --limit 10

Explain output details

When --explain is enabled, reasons are printed per task, for example:

• cache miss: no prior execution record
• cache miss: input changed: src/lib.rs
• cache miss: env changed: RUSTFLAGS
• cache miss: task command changed
• cache miss: output contract changed
• cache miss: secret env changed
• cache bypass: --force supplied
• cache bypass: --no-cache supplied
• cache bypass: interactive mode

@secret_env values are never printed; reason remains generic.

Operational patterns

Validate a migration without running

broski run ci --dry-run --explain

Rebuild once, then return to normal cache flow

broski run build --force
broski run build --explain

Run high-parallelism on large graph

broski run ci --jobs 12
# implicit form must use equals
broski ci --jobs=12

Interactive task with task-level passthrough

broski dev -- --host 0.0.0.0

Failure behavior

• Unknown task: hard failure with task name.
• Invalid DSL: parse/validation diagnostics include source context.
• Invalid --jobs value: parse failure with actionable message.
• --force-isolation on interactive task: rejected.

Make/Just mapping

Intent	Make/Just pattern	Broski command
Show tasks	make help / just --list	broski list
Run pipeline	make ci / just ci	broski ci
Render dependency graph	manual / limited	broski graph ci --format text
Force execution	phony/manual	broski run ci --force
Explain rebuilds	not first-class	broski run ci --explain
Cache trim	manual cleanup scripts	broski cache prune --max-size 512

Related pages

• Watch Mode
• Annotations
• Migration Playbook
• Anti-Patterns
• Common Mistakes
• Troubleshooting