Documentation
Install, publish, troubleshoot, and contribute packages to bpm.
Installing the CLI
bpm is distributed as an npm package. Install it globally to use the CLI across all your projects.
# Install bpm globally from npm
npm install -g @dakotafabrodev/agent-bpm
# Or use npx for one-off commands without global install
npx @dakotafabrodev/agent-bpm --version
Requirements
- Node.js 18 or later
- npm 9+ (ships with Node 18+)
Verify installation
bpm --version
# should print the installed version, e.g. 0.3.0
Update to latest
npm update -g @dakotafabrodev/agent-bpm
Contributing packages
This is the package authoring path with two Stage 1 setup states: existing package repo or from-scratch package repo.
# Stage 1A - existing package repository
cd /path/to/package-repo
bpm init
# Stage 1B - new package repository
cd ~/your-workspace
bpm init my-bpm-package --from-scratch
cd my-bpm-package
# update package content + manifest
# ensure bpm.json has name, version, type, entry, repository
# keep README.md current for package page rendering
# Stage 2 - publish
bpm token set <token>
bpm publish --auth-source=stored
Suggested baseline package repository structure:
my-bpm-package/
|- .git/
|- README.md
|- bpm.json
|- package/
|- convention.md
Installing packages
This is the consumption path. Packages are typically installed into an existing agent workflow workspace to supplement AGENTS.md behavior.
# Typical install context:
# existing project or agent workspace that already uses AGENTS.md
cd /path/to/workspace
bpm init
bpm install learning-mode
# installs package behavior and updates AGENTS.md managed section
# this flow is for consuming packages, not authoring them
Token lifecycle
Create, set, unset, and clear tokens based on local workflow and troubleshooting needs.
# 1) Create token in dashboard
# https://www.usebpm.dev/dashboard
# 2) Store token locally for CLI publish
bpm token set <token>
# 3) Optional: remove env override if auth conflicts appear
unset BPM_AUTH_TOKEN
# 4) Clear stored token when rotating/revoking
bpm token clear
Troubleshooting publish auth
# Unauthorized on publish?
unset BPM_AUTH_TOKEN
bpm publish --auth-source=stored
# verify default registry host
echo "export BPM_REGISTRY_URL='https://www.usebpm.dev'" >> ~/.zshrc
source ~/.zshrc
# reset stored token if needed
bpm token clear
bpm token set <token>
CLI command glossary
Complete command reference for the current CLI.
bpm init
Initializes bpm-lock.json in an existing project directory.
bpm init [project-name] --from-scratch
Scaffolds a new package-authoring baseline in an empty directory, or in a new subdirectory when a project name is provided.
bpm install <source>
Installs a package from registry, GitHub, or local path and updates the AGENTS.md managed section.
bpm publish
Publishes the current package repository to the registry using bpm.json and README content.
bpm publish --auth-source=auto
Tries BPM_AUTH_TOKEN first, then falls back to stored token.
bpm publish --auth-source=env
Publishes using BPM_AUTH_TOKEN only.
bpm publish --auth-source=stored
Publishes using stored local token only.
bpm token set <value>
Stores registry auth token for local publish operations.
bpm token clear
Removes locally stored registry auth token.
bpm remove <name>
Removes an installed package and regenerates AGENTS.md managed section.
bpm list
Lists installed packages and aggregate token cost from lockfile.
bpm generate
Does not overwrite manual AGENTS.md content. It appends the managed section if missing, then updates only that managed section on future runs.
bpm --help
Shows global CLI help and flow guidance.
bpm publish --help
Shows publish-specific options and auth-source usage.
bpm token --help
Shows token command usage and troubleshooting notes.
bpm --version
Prints installed CLI version.