Pumbaa is a CLI and terminal UI for the Cromwell workflow engine, built for bioinformaticians running WDL pipelines. It covers the whole loop around a workflow run — prepare and validate a submission, monitor it live, debug failures down to a task's stderr, and analyze cost and resource efficiency afterwards — and ships an AI chat agent that does all of this through natural language.
- Interactive dashboard — browse, inspect, and manage workflows in a real-time TUI (
pumbaa dashboard). - Debug view — drill into a run's task tree, statuses, and logs to find the root cause of a failure (
pumbaa workflow debug). - AI chat agent — ask about your workflows in natural language: failures, costs, logs, GCS files (
pumbaa chat). - Guided submit — scaffold an inputs JSON from the WDL and preflight everything (server, inputs, file paths, dependency zip) before submitting.
- Query & inspect — list workflows and fetch metadata, inputs, and outputs from the command line.
- Diff two runs — compare inputs, options, source, and task-level differences between two executions.
- Resource & cost analysis — measure actual usage vs. allocated resources and get recommendations to cut over-provisioning.
- Local run history — describe a run when submitting it and find out later what it was for, even after the server forgot it (
pumbaa history). - Cromwell hosts — register servers under short names and switch between them with
--host prod(pumbaa host). - WDL bundling — package a workflow and all its imports into a single distributable zip (
pumbaa bundle).
curl -sSL https://raw.githubusercontent.com/lmtani/pumbaa/main/install.sh | bashPrefer not to pipe to bash? Grab a prebuilt binary from GitHub Releases — Linux, macOS, and Windows, amd64 and arm64 — or build from source:
git clone https://github.com/lmtani/pumbaa && cd pumbaa && make buildpumbaa config init # interactive setup wizard (Cromwell host, LLM provider, ...)
pumbaa dashboard # launch the interactive TUIA few common commands:
pumbaa workflow query # list recent workflows
pumbaa workflow scaffold -w pipeline.wdl # generate an inputs JSON template
pumbaa workflow submit -w pipeline.wdl -i inputs.json -D "what this run is for"
pumbaa history # what was submitted from here
pumbaa workflow metadata <workflow-id> # status of a run
pumbaa workflow debug --id <workflow-id> # interactive failure debugging
pumbaa chat # ask the AI agent about your runsThe chat agent needs an LLM provider (ollama, vertex, or gemini) — see
Configuration.
Settings are resolved in order: CLI flags > environment variables >
~/.pumbaa/config.yaml > defaults. The main environment variables:
| Variable | Purpose |
|---|---|
CROMWELL_HOST |
Cromwell server: a URL, or an alias registered with pumbaa host add |
PUMBAA_LLM_PROVIDER |
LLM backend for the chat agent: ollama, vertex, or gemini |
PUMBAA_WDL_DIR |
Directory of WDLs indexed for the agent's WDL tools |
Full reference: configuration docs.
The ANTLR-based WDL parser under pkg/wdl is a public Go API — it
parses workflows, scaffolds inputs, and validates inputs and dependency zips
without any IO. See the
package documentation.
Requires Go 1.25+.
make build # outputs dist/pumbaa
make test # run tests
make lint # golangci-lint (CI gate)
make docs-serve # preview the documentation sitecmd/cli/ # CLI entrypoint
internal/
├── domain/ # Business entities
├── application/ # Use cases and ports (hexagonal architecture)
├── infrastructure/ # External services (Cromwell, GCS, LLM)
└── interfaces/ # CLI commands and TUI
pkg/wdl/ # WDL parser (ANTLR)
docs/ # MkDocs documentation
See ARCHITECTURE.md for the full picture and testing-guidelines.md for test conventions.
Apache License 2.0 — see LICENSE.