CLI Commands¶

Reference for the Bubbaloop command-line interface.

bubbaloop Binary¶

The bubbaloop binary is a single ~13 MB Rust executable that includes CLI, daemon, MCP server, and agent runtime.

Core Commands¶

Command	Description
`bubbaloop`	Show help
`bubbaloop up`	Load skills and start daemon (agent runtime + MCP + nodes)
`bubbaloop status`	Show service and node status
`bubbaloop doctor`	Run system diagnostics
`bubbaloop daemon`	Run the daemon (node manager)
`bubbaloop mcp`	MCP server. Flags: `--stdio` (local), `-p <port>` (HTTP), `--token` (print bearer token for `.mcp.json`)
`bubbaloop login`	Authenticate Claude (API key or OAuth). Gemini uses `GEMINI_API_KEY` env var; Ollama needs no credentials.
`bubbaloop logout`	Remove stored Claude credentials
`bubbaloop login --status`	Check status across all providers (Gemini / Claude / Ollama)

Agent Commands¶

bubbaloop agent <subcommand>

Subcommand	Description
`chat [message]`	Send messages to agents (REPL if no message)
`list`	List running agents and capabilities
`setup [-a <id>]`	Configure provider, model, and identity (no daemon needed)

Options:

Option	Description
`-a, --agent <id>`	Target a specific agent (default: routes to default agent)
`-v, --verbose`	Show tool inputs and results (useful for debugging agent behaviour)
`-z, --zenoh <endpoint>`	Zenoh endpoint (default: auto-discover)

Examples:

bubbaloop agent chat "What sensors do I have?"       # Single message (plain stdout)
bubbaloop agent chat                                  # Interactive TUI REPL
bubbaloop agent chat -v                               # TUI REPL with tool debug info
bubbaloop agent chat -a camera-expert "check feeds"   # Target specific agent
bubbaloop agent list                                  # Show running agents
bubbaloop agent setup                                 # Interactive setup wizard
bubbaloop agent setup -a camera-expert               # Configure specific agent

TUI keyboard shortcuts (interactive REPL):

Key	Action
Enter	Send message
Backspace	Delete character
↑ / ↓	Scroll output history
PageUp / PageDown	Scroll output faster
Ctrl-C or `q` (empty input)	Exit

TUI colour guide: - Bold white — your messages - Cyan — agent name header - Green — agent response text - Yellow italic — tool calls in progress - Gray — tool results (verbose mode) - Red — errors

bubbaloop login [OPTIONS]

Option	Description
`--status`	Check current authentication method and validity

Authentication methods:

bubbaloop login covers Claude (Anthropic). For Gemini (recommended — free tier), set GEMINI_API_KEY env var or write the key to ~/.bubbaloop/gemini-key. For Ollama, just run an Ollama server locally.

Claude options: 1. API Key (pay-as-you-go): Paste key from console.anthropic.com 2. Claude Subscription (Pro/Max/Team): Run claude setup-token first, then paste the sk-ant-oat01-* token

Credentials stored in ~/.bubbaloop/credentials.json.

Examples:

bubbaloop login           # Interactive login (API key or OAuth token)
bubbaloop login --status  # Check current authentication method and validity
bubbaloop logout          # Remove stored credentials

Node Commands¶

bubbaloop node <subcommand>

Subcommand	Description
`init <name>`	Create a new node from template
`validate [path]`	Validate node.yaml manifest
`list`	List all registered nodes
`add <source>`	Add node from path, GitHub URL, or shorthand
`instance <base> <suffix>`	Create instance of multi-instance node
`remove <name>`	Unregister node from daemon
`build <name>`	Build the node
`clean <name>`	Clean build artifacts
`install <name>`	Install as systemd service
`uninstall <name>`	Remove systemd service
`start <name>`	Start node service
`stop <name>`	Stop node service
`restart <name>`	Restart node service
`logs <name>`	View node logs
`enable <name>`	Enable autostart
`disable <name>`	Disable autostart
`search <query>`	Search marketplace
`discover`	Discover nodes on network

Marketplace Commands¶

bubbaloop marketplace <subcommand>

Subcommand	Description
`list`	List node registry sources
`add <name> <path>`	Add a source (GitHub repo path)
`remove <name>`	Remove a source
`enable <name>`	Enable a source
`disable <name>`	Disable a source

Note: Marketplace manages sources (registries), not nodes. Use node commands for node management.

Debug Commands¶

bubbaloop debug <subcommand>

Subcommand	Description
`info`	Show Zenoh connection info
`topics`	List active Zenoh topics
`subscribe <key>`	Subscribe to Zenoh topic
`query <key>`	Query Zenoh endpoint

Command Details¶

bubbaloop up¶

One-command bootstrap. Idempotent: ensures zenohd is on :7447 and the bubbaloop daemon is on :8088 (spawning each if missing), then writes a project-scoped .mcp.json so any MCP-aware client (Claude Code, Cursor, Cline, Claude Desktop, Copilot CLI, Zed) launched in the current directory picks up the bubbaloop tools automatically. After this, agents can call node_list, node_command_send, etc., without further setup.

bubbaloop up

This is the recommended first command after install.

bubbaloop status¶

Show current system and node status.

bubbaloop status [OPTIONS]

Option	Description
`-f, --format <format>`	Output format: `table` (default), `json`, `yaml`

Examples:

bubbaloop status           # Table output
bubbaloop status -f json   # JSON output for scripting

bubbaloop doctor¶

Run system diagnostics and optionally auto-fix issues.

bubbaloop doctor [OPTIONS]

Option	Description
`-c, --check <check>`	Run specific check only: `zenoh`, `daemon`, `services`, `config`
`--json`	Output as JSON
`--fix`	Auto-fix common issues

Examples:

bubbaloop doctor           # Run all checks
bubbaloop doctor -c zenoh  # Check Zenoh only
bubbaloop doctor --fix     # Auto-fix issues
bubbaloop doctor --json    # JSON for parsing

Auto-Fix Actions: - Start zenohd if not running - Start/restart daemon service - Start bridge service - Create missing zenoh config - Create missing sources.json

bubbaloop daemon¶

Run the node manager daemon.

bubbaloop daemon [OPTIONS]

Option	Description
`-z, --zenoh <endpoint>`	Zenoh endpoint (default: tcp/127.0.0.1:7447)

Examples:

bubbaloop daemon                        # Default
bubbaloop daemon -z tcp/192.168.1.50:7447  # Remote Zenoh

bubbaloop node init¶

Create a new node from template.

bubbaloop node init <name> [OPTIONS]

Option	Description
`-t, --node-type <type>`	Node type: `rust` (default), `python`
`-o, --output <path>`	Output directory (default: ./)
`-d, --description <desc>`	Node description
`--author <name>`	Author name

Examples:

bubbaloop node init my-sensor                       # Rust node
bubbaloop node init my-sensor --node-type python    # Python node
bubbaloop node init my-sensor -o /path/to/output    # Custom location

bubbaloop node create¶

One-shot: scaffold + build + register + install + (optionally) start. Replaces the 5-6 commands init → build → add → install → start with one invocation.

bubbaloop node create <name> [OPTIONS]

Option	Description
`-t, --node-type <type>`	Node type: `rust` (default), `python`
`-o, --output <path>`	Output directory (default: ./)
`-d, --description <desc>`	Node description
`--author <name>`	Author name
`--no-build`	Skip the build step (build is run by default)
`--no-install`	Skip the systemd-install step (install is run by default)
`--start`	Start the node after install (implies install; the truly-one-shot flow)

Examples:

bubbaloop node create my-sensor --start                # Scaffold → build → install → start
bubbaloop node create my-sensor --no-build --no-install # Scaffold only (init alias)
bubbaloop node create my-sensor --node-type python --start

bubbaloop node add¶

Register a node with the daemon.

bubbaloop node add <source> [OPTIONS]

Option	Description
`-o, --output <path>`	Target directory for Git clones
`-b, --branch <branch>`	Git branch (default: main)
`-s, --subdir <path>`	Subdirectory containing node.yaml
`-n, --name <name>`	Instance name override
`-c, --config <path>`	Config file path
`--build`	Build after adding
`--install`	Install as service after adding

Source Formats: - Local path: /path/to/node or . - GitHub URL: https://github.com/user/repo - GitHub shorthand: user/repo

Examples:

bubbaloop node add .                                # Current directory
bubbaloop node add /path/to/my-node                 # Local path
bubbaloop node add user/awesome-node                # GitHub shorthand
bubbaloop node add user/repo --subdir nodes/camera  # Subdirectory
bubbaloop node add user/repo --build --install      # Full setup

bubbaloop node instance¶

Create an instance of a multi-instance node.

bubbaloop node instance <base> <suffix> [OPTIONS]

Option	Description
`-c, --config <path>`	Config file for this instance
`--copy-config`	Copy example config from base node
`--install`	Install as systemd service
`--start`	Start after creating (implies --install)

Examples:

# Create camera instance with custom config
bubbaloop node instance rtsp-camera terrace --config ~/.bubbaloop/configs/terrace.yaml

# Copy example config from base node
bubbaloop node instance rtsp-camera garden --copy-config

# Full setup: create, install, and start
bubbaloop node instance rtsp-camera entrance --config config.yaml --start

bubbaloop node list¶

List all registered nodes.

bubbaloop node list [OPTIONS]

Option	Description
`-f, --format <format>`	Output format: `table` (default), `json`
`--base`	Show only base nodes (no instances)
`--instances`	Show only instances

Examples:

bubbaloop node list              # All nodes
bubbaloop node list --base       # Base nodes only
bubbaloop node list --instances  # Instances only
bubbaloop node list -f json      # JSON output

bubbaloop node logs¶

View node logs.

bubbaloop node logs <name> [OPTIONS]

Option	Description
`-f, --follow`	Follow logs in real-time
`-n, --lines <n>`	Number of lines to show (default: 50)

Examples:

bubbaloop node logs my-node       # Last 50 lines
bubbaloop node logs my-node -f    # Follow logs
bubbaloop node logs my-node -n 100  # Last 100 lines

Pixi Tasks¶

For development, use pixi tasks:

# Build
pixi run build               # cargo build --release

# Run Services
pixi run daemon              # bubbaloop daemon
pixi run dashboard           # React dashboard dev server

# Development
pixi run check               # cargo check
pixi run test                # cargo test
pixi run fmt                 # cargo fmt --all
pixi run clippy              # cargo clippy (enforced warnings)
pixi run lint                # fmt-check + clippy

# Documentation
pixi run docs                # mkdocs serve
pixi run docs-build          # Build static docs

# Orchestration
pixi run up                  # Start all services via process-compose

Environment Variables¶

Variable	Description	Default
`BUBBALOOP_ZENOH_ENDPOINT`	Zenoh router endpoint	`tcp/127.0.0.1:7447`
`BUBBALOOP_MACHINE_ID`	Machine identifier	hostname
`BUBBALOOP_MCP_PORT`	MCP HTTP server port	`8088`
`BUBBALOOP_MCP_TOKEN`	MCP HTTP bearer token (consumed by `.mcp.json`); read with `bubbaloop mcp --token`	—
`BUBBALOOP_MCP_MODE`	MCP transport mode (`stdio` / `http`)	—
`BUBBALOOP_MCP_TOOLSETS`	Comma-separated list of MCP toolsets to expose (default: all 11)	—
`GEMINI_API_KEY`	Gemini API key (recommended — free tier)	—
`ANTHROPIC_API_KEY`	Anthropic API key for Claude agents	—
`OLLAMA_HOST`	Ollama server base URL	`http://localhost:11434`
`RUST_LOG`	Log level	`info`

Examples:

# Remote Zenoh
export BUBBALOOP_ZENOH_ENDPOINT=tcp/192.168.1.50:7447

# Debug logging
RUST_LOG=debug bubbaloop status

# Trace for specific module
RUST_LOG=bubbaloop::daemon=trace bubbaloop daemon

JSON Output¶

All commands support JSON output for scripting and LLM integration:

# System status
bubbaloop status -f json

# Diagnostics
bubbaloop doctor --json

# Node list
bubbaloop node list -f json

Parse with jq:

# Check if system is healthy
bubbaloop doctor --json | jq '.summary.failed == 0'

# Get running nodes
bubbaloop node list -f json | jq '.[] | select(.status == "running") | .name'

# Get failed checks
bubbaloop doctor --json | jq '.checks[] | select(.passed == false)'

Common Workflows¶

Fresh Install Verification¶

bubbaloop doctor --fix       # Auto-fix any issues
bubbaloop status             # Verify services running

Add and Run a Node¶

bubbaloop node add user/my-node --build --install
bubbaloop node start my-node
bubbaloop node logs my-node -f

Create Multi-Instance Setup¶

bubbaloop node add ~/.bubbaloop/nodes/rtsp-camera
bubbaloop node instance rtsp-camera cam1 --config cam1.yaml --start
bubbaloop node instance rtsp-camera cam2 --config cam2.yaml --start
bubbaloop node list --instances

Debug Connection Issues¶

bubbaloop doctor -c zenoh    # Check Zenoh specifically
bubbaloop debug info         # Show Zenoh connection info
bubbaloop debug topics       # List active topics

CLI Commands¶

bubbaloop Binary¶

Core Commands¶

Agent Commands¶

Login Commands¶

Node Commands¶

Marketplace Commands¶

Debug Commands¶

Command Details¶

bubbaloop up¶

bubbaloop status¶

bubbaloop doctor¶

bubbaloop daemon¶

bubbaloop node init¶

bubbaloop node create¶

bubbaloop node add¶

bubbaloop node instance¶

bubbaloop node list¶

bubbaloop node logs¶

Pixi Tasks¶

Environment Variables¶

JSON Output¶

Common Workflows¶

Fresh Install Verification¶

Add and Run a Node¶

Create Multi-Instance Setup¶

Debug Connection Issues¶

See Also¶