bam

The simplicity of just. The power of Bazel.

bam is a build and workflow tool that stays out of your way. Drop a YAML file in your project, list your tasks, and bam handles the rest — parallel execution, smart caching, dependency graphs, and a beautiful live UI — without asking you to restructure anything.

It scales from a one-person side project to a multi-team monorepo, and feels native to every stack.

Quick Start

Installation

# Using uv (recommended)
uv pip install bam-tool

# Using pip
pip install bam-tool

Your First Workflow

Run bam --init in any project directory. bam detects your stack and writes a ready-to-run bam.yaml (or bam.toml, with --format toml):

The generated config is plain YAML — or TOML, if you prefer — with inputs, outputs, caching, and dependencies all wired up. Here's what it produces for a Node.js project:

version: 1

tasks:
  install:
    command: npm ci
    inputs: [package.json, package-lock.json]
    outputs: [node_modules/]

  lint:
    command: npm run lint
    inputs: ["src/**/*"]
    depends_on: [install]

  test:
    command: npm test
    inputs: ["src/**/*", "tests/**/*"]
    depends_on: [lint]

  build:
    command: npm run build
    inputs: ["src/**/*"]
    outputs: [dist/]
    depends_on: [test]

Use bam --graph to visualise the dependency tree before running anything:

Then run the pipeline. Independent tasks execute in parallel automatically — bam shows live progress as a dependency tree:

Run it again. Nothing changed, so every task restores from cache instantly:

For long-running processes like dev servers, mark the task interactive: true. bam restores all dependencies from cache first, then hands the terminal directly to your process:

tasks:
  serve:
    command: npm run dev
    interactive: true
    depends_on: [build]

Features

Simple by design

• Clean YAML or TOML config — no DSL to learn, no project restructuring required
• bam <task> to run; flags for everything else
• Shell tab completion for task names
• Works with any language or toolchain
• Reusable {{variables}} with environment lookups, in the style of just

Powerful where it counts

• Parallel execution out of the box — auto-detects CPU cores
• Content-addressed caching: tasks only re-run when inputs actually change
• Topological dependency resolution with cycle detection
• Docker and inline Python runners for hermetic or scripted steps
• Full Docker control: volumes, env passthrough, user mapping, resource limits, network isolation and private registries
• Distributed cache to share hits across your whole team
• CI pipeline generation for GitHub Actions and GitLab CI

Beautiful

• Live dependency tree with per-task progress bars
• Rich error context: shows the full dependency chain and which tasks were skipped
• ASCII and DOT graph output for dependency visualisation
• Plain-output mode for CI/CD

Use Cases

Python Project

version: 1

tasks:
  lint:
    command: ruff check src/
    inputs: ["src/**/*.py", "pyproject.toml"]

  typecheck:
    command: pyright
    inputs: ["src/**/*.py"]

  test:
    command: pytest
    inputs: ["src/**/*.py", "tests/**/*.py"]
    depends_on: [lint, typecheck]

  build:
    command: python -m build
    inputs: ["src/**/*.py", "pyproject.toml"]
    outputs: ["dist/"]
    depends_on: [test]

Multi-Stage Build

version: 1

tasks:
  generate:
    command: protoc --python_out=. schema.proto
    inputs: ["schema.proto"]
    outputs: ["schema_pb2.py"]

  build-backend:
    command: go build -o backend cmd/server/main.go
    inputs: ["cmd/**/*.go", "*.proto"]
    outputs: ["backend"]
    depends_on: [generate]

  build-frontend:
    command: npm run build
    inputs: ["src/**/*.ts"]
    outputs: ["dist/"]
    depends_on: [generate]

  package:
    command: docker build -t myapp .
    inputs: ["backend", "dist/", "Dockerfile"]
    depends_on: [build-backend, build-frontend]

CLI Reference

bam uses a flat command interface — tasks run as bam <task>, management operations are flags.

Running Tasks

bam build                  # Run a task (and all its dependencies)
bam build --jobs 8         # Use 8 parallel workers
bam build --jobs auto      # Auto-detect CPUs (default)
bam build --jobs 1         # Sequential
bam build --dry-run        # Show execution plan without running
bam build --no-cache       # Disable caching for this run
bam build --plain          # Plain output for CI/CD

Live dependency tree:

📦 Tasks
├── ✓ lint               ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
├── ✓ typecheck          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
│   └── ✓ test           ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
│       └── ✓ build      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%

✓ Successfully executed 4 task(s)

Error context:

✗ Task failed: test
  Dependency chain:
    ├─ lint
    ├─ typecheck
    └─ test

⊘ Skipped 1 task(s) due to failure:
  • build

Management Flags

bam --list              # List all configured tasks
bam --validate          # Validate config (YAML, deps, cycles)
bam --graph             # Show ASCII dependency graph
bam --graph-dot         # Output DOT format (pipe to Graphviz)
bam --clean-outputs     # Delete files declared in tasks' outputs
bam --clean-cache       # Clear the cache (prompts for confirmation)
bam --version           # Show version

CI Pipeline Generation

bam --ci                # Generate CI pipeline (writes file)
bam --ci-dry-run        # Preview CI YAML without writing
bam --ci-output FILE    # Write to custom path

Distributed Cache

Share cache across your team with a remote CAS server:

cache:
  local:
    enabled: true
    path: .bam/cache
  remote:
    enabled: true
    url: grpc://cas.example.com:50051
    token_file: ~/.bam/cas-token
    timeout: 30.0
    max_retries: 3

Local cache is checked first; remote is a transparent fallback. Gracefully degrades on network errors. See examples/remote-cache/ for a complete setup guide.

Development

git clone https://gitlab.com/cascascade/bam.git
cd bam
uv sync

uv run ruff check src tests     # Lint
uv run pyright                  # Type checking
uv run pytest                   # Tests
bam build                       # Full build via bam

Documentation

• CLI Reference — complete command documentation
• Configuration Guide — full YAML/TOML reference
• Concept Document — core concepts and design philosophy
• Architecture — system design
• Examples — sample projects

Contributing

Contributions welcome. Add tests for new functionality, follow PEP 8 and project code style, and run bam build before submitting.

License

MIT — see LICENSE.

Built with: Python 3.14+ · uv · Typer · Rich · NetworkX · Pydantic · Claude