CLI Commands

All botminter operations use the bm CLI binary. Install it with cargo install --path crates/bm or build with cargo build -p bm.

Team creation

bm init

Interactive wizard — create a new team.

bm init

Behavior:

• Prompts for workzone directory, team name, and profile
• Auto-detects GitHub auth from GH_TOKEN env var or gh auth token — prompts only if none found
• Validates the token via gh api user before proceeding
• Lists GitHub orgs and personal account for interactive selection
• Offers to create a new repo or select an existing one from the chosen org
• Lets you select project repos from the same org (HTTPS-only, validated)
• Extracts the selected profile into a new team repo with git init
• Creates GitHub repo (if new), bootstraps labels, and creates a GitHub Project (v2) with Status field
• Stops with actionable error messages if any GitHub operation fails
• Registers the team in ~/.botminter/config.yml (0600 permissions)
• First registered team becomes the default

Member management

bm hire

Hire a member into a role.

bm hire <role> [--name <name>] [-t <team>]

Behavior:

• Performs schema version guard (rejects if team schema doesn't match embedded profile)
• Extracts member skeleton from the embedded profile into team/{role}-{name}/
• Finalizes botminter.yml with the member's name
• Creates a git commit (no auto-push)
• Auto-suffix fills gaps: if 01 and 03 exist, returns 02

bm members list

List hired members for a team.

bm members list [-t <team>]

Behavior:

• Scans team/ directory for member directories
• Displays Member, Role, and Status columns
• Status reflects running/crashed/stopped from runtime state

bm roles list

List available roles from the team's profile.

bm roles list [-t <team>]

Project management

bm projects add

Add a project to the team.

bm projects add <url> [-t <team>]

Behavior:

• Derives the project name from the URL basename (strips .git suffix)
• Appends to botminter.yml projects list
• Creates projects/{name}/knowledge/ and projects/{name}/invariants/ directories
• Creates a git commit (no auto-push)
• Errors if the project name already exists

bm projects sync

Sync the GitHub Project board's Status field options with the profile definitions, and print instructions for setting up role-based views.

bm projects sync [-t <team>]

Behavior:

• Finds the team's GitHub Project board by title ({team} Board)
• Updates the built-in Status field options to match the profile's statuses definitions using the updateProjectV2Field GraphQL mutation
• Prints a table of role-based views with filter strings for manual setup in the GitHub UI
• Safe to re-run anytime (idempotent)

Team management

bm teams list

List all registered teams.

bm teams list

Behavior:

• Reads ~/.botminter/config.yml
• Displays Team, Profile, GitHub, and Default columns

bm teams sync

Provision and reconcile workspaces.

bm teams sync [--push] [-t <team>]

Behavior:

• Performs schema version guard
• Optionally pushes team repo (git push)
• Discovers hired members and configured projects
• For each member x project: creates or syncs a workspace
• Workspace creation: clones fork at member branch, clones team repo into .botminter/, surfaces files (symlinks PROMPT.md/CLAUDE.md, copies ralph.yml), assembles .claude/agents/, writes .gitignore and .git/info/exclude
• Workspace sync: pulls repos, re-copies changed files, re-assembles symlinks
• Reports summary: "Synced N workspaces (M created, K updated)"

Process lifecycle

bm start

Launch all members.

bm start [-t <team>] [--formation <name>]
# Alias:
bm up [-t <team>] [--formation <name>]

Behavior:

• Checks for ralph binary prerequisite
• Maps credentials from config to environment variables
• Discovers member workspaces
• Launches ralph run -p PROMPT.md as background process per member
• Records PIDs in state.json with atomic writes
• Verifies processes alive after 2 seconds
• For non-local formations: runs the formation manager as a one-shot Ralph session
• Writes a .topology file tracking member endpoints

bm stop

Stop all members.

bm stop [-t <team>] [--force]

Behavior:

• Graceful mode (default): runs ralph loops stop per member, polls for 60s
• Force mode (--force): sends SIGTERM immediately
• Cleans state.json entries
• Suggests bm stop -f on graceful failure

bm status

Status dashboard.

bm status [-t <team>] [-v]

Behavior:

• Displays Member, Role, Status, Started, PID table
• Shows daemon status if a daemon is running
• Checks PID liveness via kill(pid, 0)
• Auto-cleans crashed entries
• Verbose mode queries Ralph CLI commands per running member

Profile commands

bm profiles list

List all embedded profiles.

bm profiles list

Behavior:

• Displays Profile, Version, Schema, and Description columns
• Reads from compile-time embedded profiles

bm profiles describe

Show detailed profile information.

bm profiles describe <profile>

Behavior:

• Displays name, version, schema, description
• Lists available roles with descriptions
• Lists all labels with descriptions

Knowledge management

bm knowledge list

List knowledge and invariant files by scope.

bm knowledge list [-t <team>] [--scope <scope>]

Behavior:

• Lists all knowledge and invariant files in the team repo
• Filters by scope when --scope is provided
• Requires schema version 1.0

bm knowledge show

Display the contents of a knowledge or invariant file.

bm knowledge show <path> [-t <team>]

Behavior:

• Validates the path is under knowledge/ or invariants/
• Rejects path traversal attempts (e.g., ../)
• Displays file contents

bm knowledge (interactive)

Launch an interactive Claude Code session with the knowledge-manager skill.

bm knowledge [-t <team>] [--scope <scope>]

Behavior:

• Spawns a Claude Code session with the knowledge-manager skill injected
• Requires schema version 1.0

Daemon

bm daemon start

Start the event-driven daemon for a team.

bm daemon start [-t <team>] [--mode <mode>] [--port <port>] [--interval <interval>]

Behavior:

• Starts a background daemon process
• Webhook mode: listens for GitHub webhook events on the configured port; validates signatures with HMAC-SHA256 if webhook_secret is set in credentials
• Poll mode: polls the GitHub Events API at the configured interval; tracks poll state in ~/.botminter/daemon-{team}-poll.json
• Filters events by type: issues, issue_comment, pull_request
• Handles both SIGTERM and SIGINT for graceful shutdown
• Daemon log: ~/.botminter/logs/daemon-{team}.log
• Per-member logs: ~/.botminter/logs/member-{team}-{member}.log (each member's ralph output is separated)
• Writes PID to ~/.botminter/daemon-{team}.pid and config to ~/.botminter/daemon-{team}.json

bm daemon stop

Stop the running daemon for a team.

bm daemon stop [-t <team>]

Behavior:

• Sends SIGTERM to the daemon process
• Waits up to 30 seconds for graceful shutdown (the daemon forwards SIGTERM to running members with a 5-second grace period)
• Escalates to SIGKILL if the daemon doesn't exit within 30 seconds
• Cleans up PID, config, and poll state files

See Daemon Operations for detailed signal handling behavior and troubleshooting.

bm daemon status

Show daemon status for a team.

bm daemon status [-t <team>]

Behavior:

• Reports whether the daemon is running
• Displays mode (webhook/poll), port or interval, and start timestamp

Shell completions

bm completions

Generate shell completion scripts.

bm completions <shell>

Setup examples:

echo 'eval "$(bm completions bash)"' >> ~/.bashrc

echo 'eval "$(bm completions zsh)"' >> ~/.zshrc

bm completions fish > ~/.config/fish/completions/bm.fish

Development commands

These are in the root Justfile for developing botminter itself:

just build    # cargo build -p bm
just test     # cargo test -p bm
just clippy   # cargo clippy -p bm -- -D warnings

Related topics

• Getting Started — first-use walkthrough
• Workspace Model — how bm teams sync structures workspaces
• Generate a Team Repo — detailed bm init guide
• Configuration Files — daemon config, formation config, and credential fields
• Manage Knowledge — adding and organizing knowledge files