Bonfires CLI

Terminal interface for the Bonfires AI API. Chat with agents, search the knowledge graph, sync context, and render graph data — all from the command line.

Install

pip install bonfires

Or install from source:

pip install git+https://github.com/NERDDAO/bonfire-cli.git

For global install without polluting your Python environment:

pipx install bonfires

Getting Started

Run the interactive setup:

bonfire init

This will:

1. Connect to the Bonfires API
2. List your bonfires and let you pick one
3. List available agents and let you pick one
4. Save credentials to ~/.config/bonfires/config.env

You're ready to go:

bonfire chat "hello"

Commands

bonfire init

Interactive setup wizard. Connects to the API, lists your bonfires and agents, and saves config.

bonfire init

Or skip the prompts:

bonfire init --api-key YOUR_KEY --bonfire-id ID --agent-id ID

bonfire chat

Send a message to a Bonfire agent. Searches the knowledge graph by default.

bonfire chat "What do we know about auth patterns?"

Control graph behavior with --graph-mode:

bonfire chat "find related context"                        # default: regenerate
bonfire chat --graph-mode adaptive "let the agent decide"
bonfire chat --graph-mode append "add to existing graph"
bonfire chat --graph-mode static "just reply, no graph"

bonfire delve

Search the knowledge graph directly.

bonfire delve "error handling patterns"
bonfire delve -n 20 "authentication architecture"

bonfire sync

Push context to the knowledge graph. Derives a chat ID from your current git repo and branch.

bonfire sync "shipped bonfire-cli v0.1"
bonfire sync "design spec for auth" -f docs/auth-design.md

bonfire agents

List agents for the configured bonfire.

bonfire bonfires

List all bonfires.

bonfire graph

Render graph data from a JSON file or stdin.

bonfire graph results.json
cat graph.json | bonfire graph

bonfire format-chat / bonfire format-delve

Format raw API responses piped from stdin — useful for scripting.

curl -s ... | bonfire format-chat

bonfire kengram

Manage kEngrams — verifiable knowledge subgraphs. Each kEngram is a curated projection of the canonical Bonfires KG with cryptographic provenance: every pinned entity gets a SHA-256 fingerprint of its content at pin time, rolled into a merkle root.

bonfire kengram new "Session Name"             # create and set active
bonfire kengram pin <uuid>                     # pin entity (auto-fetches from KG)
bonfire kengram pin --search "rubric pipeline" # search KG, pick from results
bonfire kengram create "Entity" --summary "…"  # push new entity to KG + pin
bonfire kengram verify                         # check against canonical KG
bonfire kengram verify --local                 # local-only integrity check
bonfire kengram delete <id> --force            # remove a kEngram
bonfire kengram show                           # show active kEngram
bonfire kengram merge <src> --into <tgt>       # merge session → topic
bonfire kengram export                         # export to Obsidian .canvas
bonfire kengram list                           # list all

How verification works: verify batch-fetches all pinned entities from the canonical KG, recomputes their hashes from current KG content, and compares against the stored hashes. Per-entity status: OK (unchanged), DRIFT (KG content changed since pin), NOT IN KG (entity deleted). If the API is unreachable, falls back to local-only integrity checking.

Pin modes: Provide a UUID to auto-fetch entity metadata from the KG. Use --search to find entities interactively. Use --name/--summary/--labels for manual metadata (fallback if API is down).

Set BONFIRE_VAULT_DIR to control where manifests and canvas files are stored (default: ~/Vaults/Bonfires/vault).

Configuration

Config is loaded in this order (later overrides earlier):

1. ~/.config/bonfires/config.env (created by bonfire init)
2. .env in the current directory
3. Environment variables

Variable	Description
BONFIRE_API_URL	API base URL (default: https://tnt-v2.api.bonfires.ai)
BONFIRE_ID	Your bonfire ID
BONFIRE_AGENT_ID	Agent ID to interact with
BONFIRE_API_KEY	API key for authentication
BONFIRE_VAULT_DIR	kEngram storage directory (default: ~/Vaults/Bonfires/vault)