hugoduncan bbum — Babashka Universal Module Manager
Installs babashka tasks from versioned task libraries into a project's bb.edn.
Key Concepts
| Term | Meaning |
|---|---|
| source | Named pointer to a task library (git repo or local path) |
| task | A named babashka task provided by a library |
| explicit | Task directly requested by the user |
| implicit | Task auto-installed as a dependency |
| coord | Address of a source: key=value pairs |
| lock | Resolved SHA snapshot recorded at install time |
Config files:
~/.bbum.edn— global sources.bbum.edn— project manifest (installed tasks + project sources)bb.edn— babashka tasks (bbum splices tasks in here)bbum.edn— library manifest (lives in a task library repo)
Commands
Source Management
# Register a source (project-scoped)
bbum source add <name> git/url=<url> branch=<branch>
bbum source add <name> git/url=<url> sha=<sha>
bbum source add <name> git/url=<url> tag=<tag>
bbum source add <name> local/path=<path>
# Register globally (available in all projects)
bbum source add --global <name> git/url=<url> branch=<branch>
# Remove a source
bbum source remove <name>
bbum source remove --global <name>
# List all effective sources (global + project)
bbum source list
Cannot remove a project source while tasks are installed from it — remove those tasks first.
Browse a Source
bbum list <source>
Prints all available tasks and their docs from the library.
Install Tasks
bbum add <source> <task> [<task> ...]
# Install under a different name (avoids bb.edn conflicts)
bbum add <source> <task> --as <name>
- Checks for task-name conflicts in
bb.ednbefore writing anything. - On conflict: remove the existing task first, or use
--as <name>. - Implicit deps are installed automatically.
- Files land in
.bbum/lib/, path added tobb.ednclasspath.
Remove Tasks
bbum remove <task>
# Also remove implicit deps that become orphaned
bbum remove --with-deps <task>
- Only explicit tasks can be directly removed.
- Without
--with-deps, warns if orphaned implicits would remain.
Status
bbum status
Shows each installed task, its source, locked SHA, current SHA, and status:
| Status | Meaning |
|---|---|
ok |
Locked SHA matches current source HEAD |
outdated |
Source has moved ahead of locked SHA |
pinned |
Source is a fixed SHA — never floats |
local |
Source is a local path |
unknown |
Source no longer registered |
Exits non-zero if any task is outdated.
Update Tasks
# Update all installed tasks
bbum update
# Update a single task
bbum update <task>
Re-fetches from source, overwrites files in .bbum/lib/, updates lock in .bbum.edn. Pinned (git/sha) sources are never updated.
Common Workflows
Add a new task library and install a task:
bbum source add mylib git/url=https://github.com/org/bb-tasks branch=main
bbum list mylib
bbum add mylib some-task
Install a task under an alternative name:
bbum add mylib lint --as check
Pin a source to a specific SHA:
bbum source add mylib git/url=https://github.com/org/bb-tasks sha=abc1234
Check for outdated tasks and update:
bbum status # exits 1 if outdated
bbum update
Remove a task and its orphaned deps:
bbum remove --with-deps some-task