Skip to main content

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>

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.

Run behavior flags​

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

FlagDefaultEffectNotes
--dry-runoffCompute graph and show what would run, without execution.Useful for CI validation and migration checks.
--explainoffPrint cache miss reasons per task.Reasons are based on manifest deltas (input, env, run, outputs, etc.).
--forceoffBypass cache read and execute tasks.Explain output shows cache bypass: --force supplied.
--no-cacheoffDo not read from cache and do not write cache artifacts.Explain output shows cache bypass: --no-cache supplied.
--watchoffRe-run target graph on input changes.See Watch Mode.
--force-isolationoffForce strict isolation for graph tasks.Not supported for interactive tasks.
--jobs <n>autoOverride worker concurrency.Explicit run supports --jobs <n>. Implicit run supports --jobs=<n>.

Global flags​

FlagEffect
--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.

ModeBehavior
default (doctor)Reports and repairs stale runtime state.
--no-repairReport-only mode, no mutation.
--repairExplicit 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.

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​

IntentMake/Just patternBroski command
Show tasksmake help / just --listbroski list
Run pipelinemake ci / just cibroski ci
Render dependency graphmanual / limitedbroski graph ci --format text
Force executionphony/manualbroski run ci --force
Explain rebuildsnot first-classbroski run ci --explain
Cache trimmanual cleanup scriptsbroski cache prune --max-size 512