CLI Commands and Flags

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

Command forms

broski --workspace <path> <command>
broski                                          # no subcommand: prints long help, exits 0
broski --help | -h
broski --version | -V
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>] [--explain]
broski history [<task>] [--limit <N>]

Resolution rules

1. Subcommands win over task names — run, list, graph, doctor, cache, tui, history all shadow a task of the same name.
2. Use broski run <task> when you want explicit task resolution (or when your task happens to be named one of the subcommands above).
3. This isn't a hardcoded blocklist: any string that doesn't match one of clap's declared subcommands falls through to an external_subcommand catch-all, which is what makes broski <task> work at all. help is clap's auto-generated help subcommand; version isn't a subcommand at all — it's the global -V/--version flag — so a task literally named version is not shadowed the same way run/list/etc. are.

Run behavior flags

These flags apply to broski <task> and broski run <task>, except --tui/--theme, which are not recognized by implicit invocation (broski <task> --tui passes --tui through as a literal task argument instead of launching the dashboard — use broski run <task> --tui explicitly).

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.	See Cache Explainability for the exact reason strings.
--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.	Requires Linux + bwrap. Not supported for interactive tasks.
--jobs <n>	auto (CPU count)	Override worker concurrency.	Explicit run supports space-separated --jobs <n>. Implicit invocation requires --jobs=<n> (equals form) — the space form is rejected with an actionable error telling you to use broski run.
--tui	off	Render this run through the live TUI dashboard instead of the spinner output. run-only flag.	Mutually exclusive with --dry-run and --watch only. --explain is supported alongside --tui (as of v0.7.0). See TUI Dashboard.
--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. Default ..
-h, --help	Print help (top-level or per-subcommand) and exit 0.
-V, --version	Print broski <version> and exit 0.

Running broski with no subcommand at all prints the full long-help text and exits 0 — it does not error.

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 --force-isolation
broski test -- --grep slow

run (and implicit invocation) take exactly one task name. There is no multi-target form — broski run build api release does not build three targets; api and release would be parsed as trailing passthrough arguments forwarded to build's own script. To run several targets, either invoke them separately or make one orchestration task depend on the others (ci: lint test build) and run that.

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)	Repair is on by default — repair is enabled unless --no-repair is passed. Reports and repairs stale runtime state.
--no-repair	Report-only mode, no mutation.
--repair	Explicit repair mode (same as default; --repair --no-repair together is rejected by the CLI parser).

doctor also probes strict-isolation support: it prints strict isolation tasks: <n> when any task declares @isolation strict, followed by strict isolation probe: ok or strict isolation probe: warning. On macOS specifically, if any task is configured for strict isolation, it prints an explicit warning that strict sandboxing is unsupported on that platform (isolation silently falls back to best_effort at run time).

When an active runtime lock is live, doctor does not just skip the destructive part and still report — it aborts the whole command with another Broski execution is active; cannot run doctor sweep while lock is live and exits non-zero.

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, or (with no task) open an interactive launcher to pick one. Full reference — key map, slash commands, themes, stats panel, interactive-task suspend behavior — lives on its own page: TUI Dashboard →.

Quick summary:

• broski tui — launcher: filter tasks, type a target, hit Enter, watch it run, land back in the launcher.
• broski tui <task> — dashboard for one target directly. No --dry-run/--watch flags exist on this subcommand at all (nothing to be exclusive with).
• broski run <task> --tui — the same dashboard via run; mutually exclusive with --dry-run/--watch on this form specifically, but not with --explain.
• One output-formatting asymmetry worth knowing: after the dashboard closes, broski run <task> --tui prints the same cache hits: / executed: / dry-run: / explain-reasons summary as a normal run, but broski tui <task> prints only cache hits: / executed: — no dry-run line, no explain-reason dump — even if --explain was passed. The reasons are still visible live, inside the dashboard's log pane, while it's running.

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

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, up to 10 reasons per task are printed (with a "+N more changes" overflow line beyond that), plus a per-phase timing breakdown. For the exact reason strings and timing format, see Cache Explainability. @secret_env values are never printed; the reason for a secret change always stays 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.
• --jobs <n> (space form) on implicit invocation: rejected outright with an actionable message pointing you at broski run <task> --jobs <n>. This fires even if <n> itself is a valid number — it's a syntax rejection, not a parse-value failure.
• Invalid --jobs=<n> value: parse failure with actionable message.
• --force-isolation on interactive task: rejected.
• --force-isolation on non-Linux, or without bwrap on PATH: rejected at run start.

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

• TUI Dashboard
• Watch Mode
• Annotations
• Cache Explainability
• Migration Playbook
• Anti-Patterns
• Common Mistakes
• Troubleshooting