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.
# Using uv (recommended)
uv pip install bam-tool
# Using pip
pip install bam-toolRun bam --init in any project directory. bam detects your stack and writes a ready-to-run bam.yaml:
The generated config is plain YAML — 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]Simple by design
- Clean YAML 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
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
- 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
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]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]bam uses a flat command interface — tasks run as bam <task>, management operations are flags.
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/CDLive 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
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 # Clean cache (prompts for confirmation)
bam --clean-force # Clean cache without confirmation
bam --version # Show versionbam --ci # Generate CI pipeline (writes file)
bam --ci-dry-run # Preview CI YAML without writing
bam --ci-output FILE # Write to custom pathShare 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: 3Local cache is checked first; remote is a transparent fallback. Gracefully degrades on network errors. See examples/remote-cache/ for a complete setup guide.
git clone https://gitlab.com/cascascade/bam.git
cd bam
uv syncuv run ruff check src tests # Lint
uv run pyright # Type checking
uv run pytest # Tests
bam build # Full build via bam- CLI Reference — complete command documentation
- Configuration Guide — full bam.yaml reference
- Concept Document — core concepts and design philosophy
- Architecture — system design
- Examples — sample projects
Contributions welcome. Add tests for new functionality, follow PEP 8 and project code style, and run bam build before submitting.
MIT — see LICENSE.
Built with: Python 3.14+ · uv · Typer · Rich · NetworkX · Pydantic · Claude