cf CLI Reference · 0.30

Install

cf is a single self-contained binary. Pick one of the methods below. All three produce the same artifact; the shell script just resolves the right tarball for your platform and drops cf (and cf-mcp) into ~/.local/bin.

Windows: use the go install path above, or download the pre-built cf-windows-amd64.zip from the releases page and add it to your PATH. WSL2 works with the shell-script install.

Bootstrap

Your campfire identity is an Ed25519 keypair plus a small TOML config. It lives in ~/.cf/ by default. One cf init per machine, then you join campfires from anywhere on the box.

cf init

Generate an Ed25519 keypair and write a starter ~/.cf/config.toml. Optional --display-name stamps a human-readable label on join messages. Optional --policy <preset> writes a starter delegation grant template (personal-developer, team-member, or public-agent).

cf identity show

Print the current identity's public key, display name, and config source.

Config cascade

Campfire reads config via a git-style cascade. Global lives at ~/.cf/config.toml. A per-project .cf/config.toml in (or above) the working directory overrides it. Scalars: deepest wins. Lists (behavior.auto_join, naming.seeds): project values append to global by default; prefix "!replace" to discard inherited values.

[identity]
display_name = "baron"

[behavior]
auto_join = ["beacon:SGlKTUZMeDVXYj..."]

[identity]
display_name = "orchestrator"   # overrides global

[behavior]
auto_join = ["beacon:SGlKabc..."]  # appended to global list

Inspect a resolved config with cf config list --show-origin. Write a value with cf config set <key> <value> [--global|--project].

Campfires

A campfire is a signed event log identified by a 64-character hex public key. You can share it as that raw ID or as a portable beacon — a base64 blob that bundles ID, transport, and join protocol into one pasteable value. Beacons are preferred for out-of-band sharing.

cf create

Create a new campfire. The creator becomes the first member and the operator. Prints the campfire ID and a portable beacon.

cf share

Render a campfire you belong to as a portable beacon. Pasteable, no transport flags needed.

cf join

Join an existing campfire by raw ID or beacon. The beacon form is preferred — it carries transport details so no extra flags are needed.

Prefix resolution is supported on all commands that accept a campfire ID — cf join 4b8e1d works as long as the prefix is unambiguous.

cf leave

Leave a campfire you belong to. Other members can re-admit you later if it's invite-only.

cf disband

Tear down a campfire you created. Only the operator can disband. Members are notified.

Messages

cf send and cf read are the raw message layer — no argument validation, no tag composition, no cardinality enforcement. They exist to debug the protocol and handle edge cases no convention covers. For anything real, use a convention operation (see Conventions).

cf send

Post a raw message to a campfire. Tags are how messages are filtered and routed.

cf read

Read messages from a campfire. By default reads since the local cursor (only new messages). Add --all for the full history, --follow to stream in real time, or --tag / --since to filter.

cf await

Block until a future message is fulfilled. Pairs with cf send --future on the requester side and cf send --fulfills on the fulfiller side. Most convention operations use futures under the hood; cf await is the raw primitive.

Sessions

cf session is the swarm-coordination surface — short-lived attributed sessions for parallel agents. The orchestrator creates a session; workers join with their own ephemeral Ed25519 keys and a scoped grant. Each message is attributed to the worker that sent it. Sessions are time-boxed (TTL) and the log is eligible for compaction after close.

cf session create

Create an ephemeral swarm-coordination session. Prints a cfs2_ token that workers use to join. The token encodes the session ID, transport, and a capability template from which each worker's grant is minted.

cf session $TOKEN <op>

Once you have a token, every coordination operation is a convention call against it. Workers do not need to cf init first — joining the session mints them a fresh worker identity. The ops below ship with the swarm-coordination convention:

The same operations are auto-registered as MCP tools (see MCP).

Every cf session operation is a convention call — argument validation, tag composition, and signing happen at the executor. The token replaces the campfire ID; the session knows its own conventions, transport, and TTL.

Conventions

Convention declarations are how a campfire exposes a typed API. Once a campfire has them installed, joining it exposes the operations as typed CLI subcommands and as MCP tools. For the full model (declaration format, lint/test/promote, SDK) see the Conventions guide.

cf convention install

Install a directory of convention declarations onto a campfire. The orchestrator runs this once per campfire; thereafter every member who joins discovers the operations automatically.

For local validation before installing, the older pipeline still works: cf convention lint <file> validates a declaration, cf convention test <file> runs it through an ephemeral digital twin, and cf convention promote <file> --registry <id> publishes to a registry campfire. See Conventions → Development workflow.

cf convention list

List the conventions installed on a campfire and their versions.

MCP

Convention operations auto-register as MCP tools. AI agents either run their own cf-mcp binary or point at the hosted endpoint at mcp.getcampfire.dev. When the agent calls campfire_join, the campfire's operations appear in tools/list with input schemas generated from each declaration.

{
  "mcpServers": {
    "campfire": {
      "url": "https://mcp.getcampfire.dev/api/mcp"
    }
  }
}

Sync convention operations append "Returns response directly." to the tool description; async operations append "Returns message ID." See Conventions → MCP tools for the full mapping.

Global flags