README
¶
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.
Features
- 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.
- WDL bundling — package a workflow and all its imports into a single distributable zip (
pumbaa bundle).
Installation
curl -sSL https://raw.githubusercontent.com/lmtani/pumbaa/main/install.sh | bash
Prefer 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 build
Quick start
pumbaa config init # interactive setup wizard (Cromwell host, LLM provider, ...)
pumbaa dashboard # launch the interactive TUI
A 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 # preflights, then submits
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 runs
The chat agent needs an LLM provider (ollama, vertex, or gemini) — see
Configuration.
Configuration
Settings are resolved in order: CLI flags > environment variables >
~/.pumbaa/config.yaml > defaults. The main environment variables:
| Variable | Purpose |
|---|---|
CROMWELL_HOST |
Cromwell server URL (default http://localhost:8000) |
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.
Using the WDL parser as a library
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.
Development
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 site
Project structure
cmd/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.
Contributing
License
Apache License 2.0 — see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
cli
command
Package main provides the entry point for the pumbaa CLI.
|
Package main provides the entry point for the pumbaa CLI. |
|
internal
|
|
|
application
Package application contains error definitions for application layer use cases.
|
Package application contains error definitions for application layer use cases. |
|
application/bundle
Package create contains the use case for creating WDL bundles.
|
Package create contains the use case for creating WDL bundles. |
|
application/ports
Package ports contains domain port (interface) definitions.
|
Package ports contains domain port (interface) definitions. |
|
application/workflow
Package workflow contains use cases for workflow management operations.
|
Package workflow contains use cases for workflow management operations. |
|
config
Package config provides application configuration.
|
Package config provides application configuration. |
|
container
Package container provides dependency injection container.
|
Package container provides dependency injection container. |
|
domain/bundle
Package bundle contains domain entities for WDL bundle operations.
|
Package bundle contains domain entities for WDL bundle operations. |
|
domain/wdlindex
Package wdlindex provides domain models for WDL workflow indexing.
|
Package wdlindex provides domain models for WDL workflow indexing. |
|
domain/workflow
cost.go contains per-task cost breakdown logic for a workflow.
|
cost.go contains per-task cost breakdown logic for a workflow. |
|
infrastructure/agents/llm
Package llm provides a factory for creating LLM instances based on configuration.
|
Package llm provides a factory for creating LLM instances based on configuration. |
|
infrastructure/agents/llm/ollama
Package ollama provides an implementation of model.LLM for Ollama, allowing local models to be used with the Google Agents ADK.
|
Package ollama provides an implementation of model.LLM for Ollama, allowing local models to be used with the Google Agents ADK. |
|
infrastructure/agents/tools
Package tools provides implementations of tools for use with Google Agents ADK.
|
Package tools provides implementations of tools for use with Google Agents ADK. |
|
infrastructure/agents/tools/cromwell
Package cromwell provides action handlers for Cromwell workflow operations.
|
Package cromwell provides action handlers for Cromwell workflow operations. |
|
infrastructure/agents/tools/gcs
Package gcs provides action handlers for Google Cloud Storage operations.
|
Package gcs provides action handlers for Google Cloud Storage operations. |
|
infrastructure/agents/tools/localfs
Package localfs provides action handlers for writing files in the user's working directory — e.g.
|
Package localfs provides action handlers for writing files in the user's working directory — e.g. |
|
infrastructure/agents/tools/submit
Package submit provides agent actions that help prepare a workflow submission: scaffolding an inputs template and preflighting it.
|
Package submit provides agent actions that help prepare a workflow submission: scaffolding an inputs template and preflighting it. |
|
infrastructure/agents/tools/types
Package types provides common types shared across tool handlers.
|
Package types provides common types shared across tool handlers. |
|
infrastructure/agents/tools/wdl
Package wdl provides action handlers for WDL knowledge base operations.
|
Package wdl provides action handlers for WDL knowledge base operations. |
|
infrastructure/cloudlogging
Package cloudlogging provides Cloud Logging adapter for batch logs.
|
Package cloudlogging provides Cloud Logging adapter for batch logs. |
|
infrastructure/cromwell
Package cromwell provides an implementation of ports.WorkflowRepository using the Cromwell API.
|
Package cromwell provides an implementation of ports.WorkflowRepository using the Cromwell API. |
|
infrastructure/metrics
Package metrics provides implementations for reading task metrics from various sources.
|
Package metrics provides implementations for reading task metrics from various sources. |
|
infrastructure/recommendation
Package recommendation provides implementations of the RecommendationGenerator interface.
|
Package recommendation provides implementations of the RecommendationGenerator interface. |
|
infrastructure/session
Package session provides a SQLite-based implementation of the ADK session.Service interface.
|
Package session provides a SQLite-based implementation of the ADK session.Service interface. |
|
infrastructure/templates
Package templates provides embedded HTML templates for report generation.
|
Package templates provides embedded HTML templates for report generation. |
|
infrastructure/version
Package version provides functionality for checking pumbaa version updates.
|
Package version provides functionality for checking pumbaa version updates. |
|
infrastructure/wdlindexer
Package wdlindexer provides WDL indexing infrastructure.
|
Package wdlindexer provides WDL indexing infrastructure. |
|
interfaces/cli/handler
Package handler provides CLI command handlers.
|
Package handler provides CLI command handlers. |
|
interfaces/cli/presenter
Package presenter provides terminal output formatting utilities.
|
Package presenter provides terminal output formatting utilities. |
|
interfaces/tui
Package tui provides the terminal user interface for the application.
|
Package tui provides the terminal user interface for the application. |
|
interfaces/tui/common
Package common provides shared utilities and styles for the TUI.
|
Package common provides shared utilities and styles for the TUI. |
|
interfaces/tui/dashboard
Package dashboard provides the dashboard screen for the TUI.
|
Package dashboard provides the dashboard screen for the TUI. |
|
interfaces/tui/debug
Package debug provides an interactive TUI for debugging Cromwell workflow metadata.
|
Package debug provides an interactive TUI for debugging Cromwell workflow metadata. |
|
interfaces/tui/debug/tree
Package tree provides tree visualization logic for workflow debugging.
|
Package tree provides tree visualization logic for workflow debugging. |
|
prompts
Package prompts holds the system instructions for pumbaa's LLM agents in one place, so the personas can be reviewed and iterated on together.
|
Package prompts holds the system instructions for pumbaa's LLM agents in one place, so the personas can be reviewed and iterated on together. |
|
pkg
|
|
|
wdl
Package wdl provides parsing, analysis, and bundling capabilities for WDL files.
|
Package wdl provides parsing, analysis, and bundling capabilities for WDL files. |
|
wdl/ast
Package ast defines the Abstract Syntax Tree structures for WDL documents.
|
Package ast defines the Abstract Syntax Tree structures for WDL documents. |
|
wdl/visitor
Package visitor implements a visitor pattern to build AST from parse tree.
|
Package visitor implements a visitor pattern to build AST from parse tree. |
Click to show internal directories.
Click to hide internal directories.