The complete Crab ML workflow CLI cookbook

This cookbook closes the loop on the fraud-detection series. It covers every public command form exposed by the current Rust CLI under run, repro, stage, freeze, unfreeze, workflow, exp, queue, params, metrics, plots, and artifacts.

Explore the complete public workflow CLI

Scroll horizontally to explore the full diagram →

Run & author

Declare stages and control execution.

6 commands

crab run

Execute or replay declared stages

crab repro

DVC-compatible workflow execution alias

crab stage add

Create or replace one stage declaration

crab stage list

List discovered stages

crab freeze

Skip selected stages until unfrozen

crab unfreeze

Restore normal invalidation

52 public command forms across six families. Select a family to inspect its operator boundary; the internal checkpoint control protocol is intentionally excluded.

crab workflow checkpoint is deliberately absent. It is a hidden stage-to-supervisor control protocol, not a user command. Aliases such as crab exp list → crab exp ls and crab exp branch → crab exp promote do not add a second behavior boundary.

Run and author stages

# Declarative DAG
crab run --validate
crab run --dry --explain-miss
crab run --parallelism 2 --json
crab repro train --downstream

# Inline cached stage
crab run --name smoke-model \
  --deps models/fraud-model.pkl \
  --deps src/smoke_model.py \
  --outs metrics/smoke.json \
  -- python3 src/smoke_model.py models/fraud-model.pkl \
    --report metrics/smoke.json

# Authoring helpers
crab stage add -n smoke-model \
  -d models/fraud-model.pkl \
  -d src/smoke_model.py \
  -o metrics/smoke.json \
  python3 src/smoke_model.py models/fraud-model.pkl \
    --report metrics/smoke.json
crab stage list --json

# Shared stage policy
crab freeze ingest train
crab run
crab unfreeze ingest train

Freeze changes the workflow declaration. Review and commit that YAML change when collaborators and CI should share it.

Inspect workflow state and lockfiles

crab workflow status --json
crab workflow dag
crab workflow dag --format mermaid

crab workflow journal ls
crab workflow journal show <run-id>
crab workflow journal gc --keep 50

For a multi-team repository, preview and apply split lockfiles:

crab workflow lockfile split --dry-run
crab workflow lockfile split --update-config
crab run --recursive --dry

Resolve a Git conflict in one lockfile, then rerun affected stages:

crab workflow lockfile resolve --path crab.lock
crab run --dry --explain-miss

The top-level status surface can inspect the same workflow state:

crab status --workflow --json
crab status --workflow --why train

Run the complete experiment lifecycle

# Create and inspect
crab exp save -n baseline
crab exp run -S train.learning_rate=0.2 -n candidate --json
crab exp show candidate --json
crab exp ls
crab exp diff baseline candidate --json

# Organize and materialize
crab exp rename candidate weekly-candidate
crab exp apply weekly-candidate
crab exp promote weekly-candidate --branch experiments/weekly-candidate

# Checkpoint lineage
crab exp run --resume <checkpoint-experiment>
crab exp reset <checkpoint-experiment> --checkpoint <checkpoint-id>

# Maintain local state
crab exp remove old-candidate
crab exp gc --keep 100 --dry-run
crab exp clean

apply changes current workspace files. promote creates a Git branch. reset changes an experiment checkpoint lineage. Inspect the experiment before choosing among them.

Submit and operate queued experiments

The crab exp family provides submission plus short worker aliases:

crab exp queue \
  -S train.learning_rate=0.1,0.2,0.3 \
  -S train.l2=0.0,0.01,0.1 \
  --json
crab exp start --jobs 2
crab exp status --json
crab exp stop

The dedicated queue family adds task-level operations:

crab queue start --jobs 2
crab queue status --json
crab queue logs <task-id>
crab queue kill <task-id>
crab queue remove --failed
crab queue stop

Use graceful stop for planned shutdown. Preserve logs before killing or removing failed tasks.

Publish workflow and experiment state through a remote

These commands require a configured, writable crab:// remote. They are not part of the dependency-free local quickstart:

crab run --cache-push
crab workflow push-cache --all --json
crab exp push weekly-candidate
crab exp pull weekly-candidate

Read params, metrics, and plots

crab params show --json
crab params diff origin/main HEAD --json

crab metrics show --json
crab metrics diff origin/main HEAD --json
crab metrics plot --format html --output metrics-plots/index.html

crab plots show --format html --output plots/index.html
crab plots diff origin/main HEAD --format html --output plot-diff.html
crab plots templates

These commands read recorded evidence. They do not execute a missing stage. Generate missing metrics or plot sources with crab run first.

Manage immutable artifacts and mutable labels

# Inspect
crab artifacts list --json
crab artifacts show fraud-model --json

# Capture and retrieve immutable bytes
crab artifacts version create fraud-model --json
crab artifacts get fraud-model \
  --version <version-id> \
  --output validation/fraud-model.pkl \
  --json

# Move and audit a mutable label
crab artifacts promote \
  fraud-model \
  <candidate-version> \
  production \
  --expected <current-production-version> \
  --json
crab artifacts history fraud-model --json

# Consumer resolution
crab artifacts get fraud-model \
  --stage production \
  --output runtime/fraud-model.pkl

Creation captures clean output bytes. Promotion copies no payload and should use --expected in automation. Retrieval by version is immutable; retrieval by stage first resolves a mutable label.

Alternate operational surfaces

Two optimization commands expose the same cache and journal maintenance boundaries for operators already using crab optimize:

crab optimize workflow-cache push --all
crab optimize workflow-cache journal-gc

Prefer the direct workflow spelling in pipeline documentation. Use the optimize surface when composing broader storage and repository maintenance.

Keep the exact option tables nearby in the crab run, crab exp, crab queue, crab workflow, crab metrics, and crab plots references.

Explore the complete public workflow CLI

Scroll horizontally to explore the full diagram →

Run & author

Declare stages and control execution.

6 commands

crab run

Execute or replay declared stages

crab repro

DVC-compatible workflow execution alias

crab stage add

Create or replace one stage declaration

crab stage list

List discovered stages

crab freeze

Skip selected stages until unfrozen

crab unfreeze

Restore normal invalidation

52 public command forms across six families. Select a family to inspect its operator boundary; the internal checkpoint control protocol is intentionally excluded.

Run and author stages

# Declarative DAG
crab run --validate
crab run --dry --explain-miss
crab run --parallelism 2 --json
crab repro train --downstream

# Inline cached stage
crab run --name smoke-model \
  --deps models/fraud-model.pkl \
  --deps src/smoke_model.py \
  --outs metrics/smoke.json \
  -- python3 src/smoke_model.py models/fraud-model.pkl \
    --report metrics/smoke.json

# Authoring helpers
crab stage add -n smoke-model \
  -d models/fraud-model.pkl \
  -d src/smoke_model.py \
  -o metrics/smoke.json \
  python3 src/smoke_model.py models/fraud-model.pkl \
    --report metrics/smoke.json
crab stage list --json

# Shared stage policy
crab freeze ingest train
crab run
crab unfreeze ingest train

Freeze changes the workflow declaration. Review and commit that YAML change when collaborators and CI should share it.

Inspect workflow state and lockfiles

crab workflow status --json
crab workflow dag
crab workflow dag --format mermaid

crab workflow journal ls
crab workflow journal show <run-id>
crab workflow journal gc --keep 50

For a multi-team repository, preview and apply split lockfiles:

crab workflow lockfile split --dry-run
crab workflow lockfile split --update-config
crab run --recursive --dry

Resolve a Git conflict in one lockfile, then rerun affected stages:

crab workflow lockfile resolve --path crab.lock
crab run --dry --explain-miss

The top-level status surface can inspect the same workflow state:

crab status --workflow --json
crab status --workflow --why train

Run the complete experiment lifecycle

# Create and inspect
crab exp save -n baseline
crab exp run -S train.learning_rate=0.2 -n candidate --json
crab exp show candidate --json
crab exp ls
crab exp diff baseline candidate --json

# Organize and materialize
crab exp rename candidate weekly-candidate
crab exp apply weekly-candidate
crab exp promote weekly-candidate --branch experiments/weekly-candidate

# Checkpoint lineage
crab exp run --resume <checkpoint-experiment>
crab exp reset <checkpoint-experiment> --checkpoint <checkpoint-id>

# Maintain local state
crab exp remove old-candidate
crab exp gc --keep 100 --dry-run
crab exp clean

apply changes current workspace files. promote creates a Git branch. reset changes an experiment checkpoint lineage. Inspect the experiment before choosing among them.

Submit and operate queued experiments

The crab exp family provides submission plus short worker aliases:

crab exp queue \
  -S train.learning_rate=0.1,0.2,0.3 \
  -S train.l2=0.0,0.01,0.1 \
  --json
crab exp start --jobs 2
crab exp status --json
crab exp stop

The dedicated queue family adds task-level operations:

crab queue start --jobs 2
crab queue status --json
crab queue logs <task-id>
crab queue kill <task-id>
crab queue remove --failed
crab queue stop

Use graceful stop for planned shutdown. Preserve logs before killing or removing failed tasks.

Publish workflow and experiment state through a remote

These commands require a configured, writable crab:// remote. They are not part of the dependency-free local quickstart:

crab run --cache-push
crab workflow push-cache --all --json
crab exp push weekly-candidate
crab exp pull weekly-candidate

Read params, metrics, and plots

crab params show --json
crab params diff origin/main HEAD --json

crab metrics show --json
crab metrics diff origin/main HEAD --json
crab metrics plot --format html --output metrics-plots/index.html

crab plots show --format html --output plots/index.html
crab plots diff origin/main HEAD --format html --output plot-diff.html
crab plots templates

These commands read recorded evidence. They do not execute a missing stage. Generate missing metrics or plot sources with crab run first.

Manage immutable artifacts and mutable labels

# Inspect
crab artifacts list --json
crab artifacts show fraud-model --json

# Capture and retrieve immutable bytes
crab artifacts version create fraud-model --json
crab artifacts get fraud-model \
  --version <version-id> \
  --output validation/fraud-model.pkl \
  --json

# Move and audit a mutable label
crab artifacts promote \
  fraud-model \
  <candidate-version> \
  production \
  --expected <current-production-version> \
  --json
crab artifacts history fraud-model --json

# Consumer resolution
crab artifacts get fraud-model \
  --stage production \
  --output runtime/fraud-model.pkl

Creation captures clean output bytes. Promotion copies no payload and should use --expected in automation. Retrieval by version is immutable; retrieval by stage first resolves a mutable label.

Alternate operational surfaces

Two optimization commands expose the same cache and journal maintenance boundaries for operators already using crab optimize:

crab optimize workflow-cache push --all
crab optimize workflow-cache journal-gc

Prefer the direct workflow spelling in pipeline documentation. Use the optimize surface when composing broader storage and repository maintenance.

Keep the exact option tables nearby in the crab run, crab exp, crab queue, crab workflow, crab metrics, and crab plots references.

The complete Crab ML workflow CLI cookbook

Run & author

Run and author stages

Inspect workflow state and lockfiles

Run the complete experiment lifecycle

Submit and operate queued experiments

Publish workflow and experiment state through a remote

Read params, metrics, and plots

Manage immutable artifacts and mutable labels

Alternate operational surfaces

Check the decision, not your memory.

Promote and roll back ML artifacts safely

Explore all guides

Related guides

The complete Crab ML workflow CLI cookbook

Run & author

Run and author stages

Inspect workflow state and lockfiles

Run the complete experiment lifecycle

Submit and operate queued experiments

Publish workflow and experiment state through a remote

Read params, metrics, and plots

Manage immutable artifacts and mutable labels

Alternate operational surfaces

Check the decision, not your memory.

Promote and roll back ML artifacts safely

Explore all guides

Related guides