bcd commands

bcd is one binary with one subcommand per mode or local task. This page lists every subcommand the code registers in daemon/cmd/bcd/main.go, its flags exactly as defined there, what it does, and how it exits. The overview explains what each mode is for, installing bcd covers the install script that runs most of these for you, and the config.toml reference covers the file most of them read. When something goes wrong, start with bcd doctor (below) and troubleshooting.

Usage and exit codes

bcd <command> [flags]
bcd <command> -h    flags of one command
bcd help            the command list (also -h, -help, --help)
bcd --version       same as bcd version (also -version)

Every command uses Go's flag package: flags are -name value or --name=value, booleans are --name or --name=false. No command takes positional arguments. bcd never echoes an unexpected argument, so a token pasted on the command line does not reach a log:

$ bcd join bcjt_jt_01...
bcd join: takes no positional arguments
bcd join reads the join token from BCD_JOIN_TOKEN, stdin or --token-file, never from arguments

An unknown command name is echoed only when it looks like one (lower-case letters and -, at most 32 characters); anything else prints bcd: unknown command alone.

The commands

Two names exist that are not for operators: __bcx-exec is bcd re-executing itself as the plugin sandbox's shim, and helper-call exists only in builds with the helpere2e tag, where the root helper end-to-end test sends one JSON request from standard input to [helper] socket. A release build has neither in its command list.

bcd node

Runs the node agent: the session to the gateway, the journal, inventory, NodeSpec convergence, commands, tunnels, telemetry and self-update.

At start it loads the configuration, refuses dev_insecure_h2c in a host build, loads the identity from data_dir (identity.json and node.key), opens the journal, starts the bcx plugins of [plugins] dir, checks [kubernetes], prepares self-update, switches to the WebSocket fallback when [websocket] url is set, serves bcd status on socket_path, and with [imds] listen serves the instance metadata service. With [helper] socket it sends its privileged work to bcd helper and reads the root-only inventory (DMI serials, DIMMs, NVMe health) through it; see privilege separation. A host build running as an ordinary user without [helper] starts anyway, but claims no GPU binding capability and fails every GPU hold at once as node-unprivileged (da60bbd).

It logs JSON lines to standard error ([log]), and runs until SIGINT or SIGTERM. Exits:

• 0 on a signal, or after a self-update swapped the binary slots, in which case main execs the entrypoint (the new binary) with the same arguments.
• 1 when it cannot start (bcd node: agent: this node has not joined (run bcd join), a journal of another node, an invalid [kubernetes] value) or when the certificate is revoked (agent: this node's certificate was revoked).

bcd node --config /etc/bcd/config.toml

bcd site

Runs the site agent: the same agent with role site (BMC operations, site.httpProxy, boot entries) and, with [boot] listen set, the boot server (proxy DHCP, TFTP, iPXE, the image cache).

It refuses a data directory whose identity is not a site's ("this data directory holds a node identity; join with a site token (bcd join --role site)", exit 1). With [boot] listen, join-encryption.jwk must sit next to the configuration file (exit 1 otherwise), and proxy_dhcp or tftp need [boot] server_ip (IPv4) and [boot] url (exit 2). Without [boot] listen it logs a warning and serves no PXE machine. [helper] is ignored.

BCD_JOIN_TOKEN=bcjt_... bcd join --role site --config /etc/bcd/config.toml
bcd site --config /etc/bcd/config.toml

bcd ramdisk

Runs inside the PXE ramdisk a site agent boots. It has no config.toml: it reads the bc.* parameters from the kernel command line (listed in the ramdisk), joins with the discovery attestor as role ramdisk unless the data directory already holds an identity, then runs the agent.

A missing or malformed boot parameter, or an http:// gateway in a host build, exits 2. A bc.jwk that does not match its pin exits 1 ("bc.jwk does not match the join encryption pin"). Logs are always JSON. The OS a deploy.image installs gets a config.toml rendered from the same parameters (with the default data_dir) and the same join-encryption.jwk.

bcd helper

Runs as root beside an unprivileged bcd node and serves its typed privileged operations on [helper] socket. See running bcd node unprivileged for the units and privilege separation for the operations.

Before it listens, it refuses to start (exit 1) when:

It then creates the socket's directory if needed, binds the socket (mode 0660, group the node account's primary group) in a private directory and renames it into place, re-arms the self-update watchdog for a swap still waiting for confirmation, and serves until a signal. Each refused connection is logged as helper: connection refused with the reason; see troubleshooting.

sudo bcd helper --config /etc/bcd/config.toml

bcd sim

Runs --nodes real node agents in one process against the configuration's gateway, each on a fake machine. It exists only in fakehw builds (go build -tags fakehw); a host build prints bcd sim: needs a fakehw build (go build -tags fakehw) and exits 2. See bcd sim for what each simulated machine does.

When any machine has not joined, it reads one token from BCD_JOIN_TOKEN or standard input (exit 2 without one) and needs join-encryption.jwk next to the configuration (exit 1 without it). At most 16 joins run at once.

printf '%s\n' "$SIM_TOKEN" | bcd sim --config ./sim.toml --nodes 5 --seed 100

bcd join

Joins this machine to the fleet and writes node.key and identity.json under data_dir. The token comes from BCD_JOIN_TOKEN, else the first line of standard input (at most 4 KiB, a leading byte-order mark dropped), else --token-file; never from an argument.

What it does, in order:

1. Loads config.toml, or, when the file does not exist and --server is given, builds one from the well-known document checked against the three pin flags (joining from the well-known document).
2. With --reset: as root, renames identity.json, node.key, node.key.next and journal.db to <name>.reset-<UTC time>. Without --yes it prints what it would move and exits 2. See joining again with --reset.
3. If an identity loads, prints already joined as <node> (site <site>, role <role>) and exits 0, without reading a token. Under [helper] it hands identity.json and node.key to the [helper] user first.
4. Otherwise reads the credential, seals the token to the pinned JoinService key, and calls Join with the hardware claims. Retryable failures (UNAVAILABLE, RESOURCE_EXHAUSTED, deadlines) retry with jittered back-off up to 20 attempts, or exactly when the gateway's grpc-retry-pushback-ms says; a pending approval waits and asks again; a tpm join answers up to 3 challenge rounds.
5. Verifies the signed JoinResponse, stores the key and identity, writes a bootstrapped config.toml (0600) and join-encryption.jwk (0644), removes the token file, and prints joined as <node> (site <site>, role <role>); certificate valid until <time>.

# the token on standard input, as the install script does it
printf '%s\n' "$TOKEN" | sudo bcd join --config /etc/bcd/config.toml
# a site agent
sudo BCD_JOIN_TOKEN=bcjt_... bcd join --role site
# with the TPM, no token
sudo bcd join --attestor tpm < /dev/null
# an OS a deploy installed, with no config.toml yet
sudo bcd join --server https://compute.example.com --token-file /etc/bcd/join-token --node-id node_01k5w... \
  --serving-ca-pin sha256/... --join-signing-pin sha256/... --join-encryption-pin sha256/...

The join flow, the attestors and the server's refusals are covered in joining nodes and attestation.

bcd status

Asks a running agent (node, site or ramdisk) for its state over its status socket. The socket is created mode 0600 in a 0700 directory, so only the account the agent runs as (or root) can ask.

node       node_01k5w... (site fsn1, role node)
bcd        0.1.0, boot 6f0c...
session    connected (epoch 14, clock offset -3 ms)
spec       applied 42, observed 42
  devices    CONVERGED
  host       PROGRESSING Retrying: helper: not allowed
commands   0 running, 0 waiting for a spec
events     0 unacked, 0 waiting, 0 metrics dropped
identity   certificate until 2026-10-06T02:11:00Z, node key in the TPM, trust bundle v3, signed intent enforced

The GPU, kubernetes and telemetry lines that follow are described in bcd status. The JSON object has nodeId, siteId, role, version, bootId, incarnation, journalId, connected, epoch, clockOffsetMs, appliedGeneration, observedGeneration, sections (section, state, reason, message), running, deferred, pendingEvents, droppedMetrics, waitingEvents, certificateNotAfter, nodeKey (tpm or file), trustVersion, commandSigning, and, when present, gpus, kubernetes and telemetry. It exits 1 with the node agent is not running (no socket at <path>) when nothing listens.

bcd doctor

Checks the host and prints one line per check: status (ok, warn or fail), check name, detail.

It exits 1 when any check fails and 0 otherwise; warnings never fail it. A configuration that does not load fails config and skips every check that needs it (Kubernetes, helper, gateway, identity, update). Run it as root: the helper directory checks and the DMI finding only run or read correctly as root. The install script runs it before the join and only warns on failure.

sudo bcd doctor --config /etc/bcd/config.toml

An excerpt (a GPU host has many more lines):

ok    config    /etc/bcd/config.toml: gateway https://gw.eu.example.com, site fsn1
ok    nvml      driver …, 8 GPUs
ok    hardware  host: 8 GPUs, … inventory sections hashed
ok    kvm       /dev/kvm present
ok    iommu     16 IOMMU units
ok    gateway   gw.eu.example.com:443 reachable in 4ms
ok    identity  node node_01k5w… (site fsn1, role node), certificate valid for 14h12m0s
warn  update    no [update] release_pins: self-update is refused (reinstall to upgrade)
ok    clock     synchronized (estimated error … µs)

The real-host preflight (systemd, delegation, the KVM cause, vfio, iommu-groups, clock and the inventory findings; e2a0cf0) runs only in host builds. The order is: configuration, NVML, hardware, host checks, GPU checks, Kubernetes and helper checks, gateway, identity, configuration checks, then the preflight.

Doctor checks

The preflight drops findings whose status is ok, and the kvm, iommu and cgroup findings, which other checks already report.

bcd hardware

Prints what bcd sees of this machine and the bring-up findings, without a configuration file (e82d3a8). Use it on a new server model before it joins.

The summary lists the system, CPU and NUMA nodes, memory and DIMMs, disks, NICs, GPUs, the BMC and the OS, then a Findings block with the same checks doctor's preflight prints. As an ordinary user the product UUID and serials read empty (they are root-only in sysfs) and the dmi finding says so. It exits 1 when a finding fails, and 2 for --redact without --capture or --capture in a fakehw build.

sudo bcd hardware
sudo bcd hardware --capture ./r760-h100.tar.gz --redact

bcd update

Shows the self-update state: the running version, the release floor, the pin count and threshold, the slots, a pending update and the versions that failed to start.

It reads the records from [update] slots_dir, else /usr/local/lib/bcd under [helper], else <data_dir>/bin with the records in data_dir. On a helper node those are root's, so run it as root.

version 0.9.1, release floor 12, 2 release pins (threshold 2)
slots: current a (0.9.1), other b (0.9.0)
failed: 0.9.2 (bcd 0.9.2 did not start)

See self-update for the slots and records.

bcd version

Prints bcd <version> <os>/<arch> <go version>, plus tags=<tags> for a build made with -tags (a fakehw build says tags=fakehw). The version is set at link time with -ldflags "-X main.version=<version>"; an unset one is 0.0.0-dev.

$ go build -tags fakehw -ldflags "-X main.version=0.1.0" ./cmd/bcd && ./bcd version
bcd 0.1.0 linux/amd64 go1.26.0 tags=fakehw

The module requires Go 1.26 (daemon/go.mod); the Go version printed is the toolchain's that built the binary.