CLI¶

The ginkgo CLI is the main operator surface for authoring, validating, running, and inspecting workflows. Every command operates on the project rooted at the nearest ginkgo.toml.

Command Overview¶

ginkgo init: Scaffold a new project — ginkgo.toml, a starter workflow.py, the canonical layout, and a skills/ directory for coding agents. See Working with Coding Agents.
ginkgo run: Build the expression tree, validate the workflow, evaluate ready tasks, and record the run. The command you reach for most.
ginkgo test: Validate a workflow without executing task bodies. Use it in CI or before a long run to catch wiring errors early.
ginkgo inspect: Inspect the resolved task graph (inspect workflow) or the structure of a recorded run (inspect run <run_id>).
ginkgo debug: Inspect a finished run — task status, timing, logs, and cache decisions — from its recorded run directory.
ginkgo doctor: Check a workflow and its environment for problems: missing environments, unresolved secrets, malformed config.
ginkgo report: Render a finished run as a self-contained HTML report. See Assets and Reports.
ginkgo cache: List, clear, and prune cached task results. See Caching and Provenance.
ginkgo asset: List and inspect typed, versioned task outputs. See Assets and Reports.
ginkgo models: List model assets together with their recorded metrics.
ginkgo notebooks: List the rendered notebook HTML artifacts produced by runs.
ginkgo env: List and reset the Pixi and container environments backing shell tasks. See Environments.
ginkgo secrets: List and validate the secret references a workflow resolves at run time.

Run ginkgo <command> --help for the full flag set of any command.

Running Workflows¶

ginkgo run workflow.py
ginkgo run workflow.py --jobs 8 --cores 32 --memory 64
ginkgo run workflow.py --dry-run

ginkgo run builds the expression tree, validates the workflow, evaluates ready tasks subject to the --jobs, --cores, and --memory budgets, and writes run history under .ginkgo/runs/. Run it from a project root with no path argument and Ginkgo discovers the canonical workflow.py entrypoint.

--dry-run resolves the graph and computes cache keys without executing any task body — the fastest way to confirm a workflow is wired correctly.

--agent swaps the live terminal UI for a stream of newline-delimited JSON events, for programmatic use by AI coding agents — see Working with Coding Agents.

Validation And Diagnostics¶

Use these commands to inspect a workflow without committing to the full workload:

ginkgo test --dry-run
ginkgo doctor workflow.py
ginkgo debug <run_id>

ginkgo doctor catches environment and configuration problems before a run. Pass --json for structured output suitable for programmatic use:

ginkgo doctor workflow.py --json

ginkgo debug is most useful after the fact: once a run directory exists, it surfaces recorded task status, logs, and cache behavior without manually navigating .ginkgo/runs/.

ginkgo cache has several subcommands beyond listing:

ginkgo cache ls                          # list cached task results
ginkgo cache explain --run <run_id>      # explain cache decisions for a run
ginkgo cache prune --older-than 7d       # remove entries older than a duration
ginkgo cache prune --max-size 10GB       # remove entries to stay under a size limit
ginkgo cache prune --max-entries 500     # remove entries to stay under an entry count
ginkgo cache clear <cache_key>           # remove a specific cache entry

cache prune requires at least one of --older-than, --max-size, or --max-entries. Add --dry-run to preview what would be removed.

A Typical Loop¶

For local development, a practical cycle looks like this:

author and adjust tasks in code
check the wiring with ginkgo run --dry-run (or ginkgo test)
run with ginkgo run
inspect failures or cache reuse with ginkgo debug

Because Ginkgo caches completed tasks, iterating on a later stage of a workflow re-executes only that stage — earlier tasks serve straight from cache.