agents/commands: read-only command cheat sheet

Adds a flag-combinations table for bw test (selectors + the
HIJKMSp/IJKMp default-flag split), bw metadata -k/-b/-f (with
the -f sensitive-data warning), bw items --blame/-f, bw verify
-o bundle:, bw hash -m/-d. Also documents the shared target-
selector grammar.

Surfaced by the left4me-integration session, where the agent
relied on bare bw test / bw metadata / bw items invocations and
missed leverage from the available flags.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-10 20:26:27 +02:00

3.4 KiB

Raw Blame History

Commands

The canonical bw-command runbook — read-only allowlist, three-tier safety envelope, after-change table, hash-diff workflow, bw debug sketch — lives in the fork's AGENTS.md. Read that first.

This file collects only the deltas specific to ckn-bw.

Apt-key changes need offline verification

Editing files under data/apt/keys/*.{asc,gpg} rotates a signing key the whole apt subsystem trusts. Trial-and-error with bw apply is the failure path: a wrong key blocks unattended upgrades cluster-wide until corrected manually.

Before touching data/apt/keys/:

Fetch the new key from its upstream source (project release page, keys.openpgp.org, etc.).
gpg --show-keys <newkey> — print the fingerprint.
Diff against the fingerprint published by the upstream source.
Only after the fingerprint matches, place the file under data/apt/keys/ and let bundles/apt consume it on the next apply.

`*.py_` suspended nodes are invisible to `bw nodes`

The repo loader (nodes.py) only matches files ending in .py. Files ending in .py_ are silently skipped. If bw nodes reports a node missing, check whether its file has been parked:

ls nodes/ | grep '\.py_$'

This is the suspension idiom, not a bug.

Vault output never leaves the terminal

The fork's runbook calls out that bw debug resolves vault magic strings transparently. In ckn-bw specifically: never echo, log, or paste decrypted values, even from a bw debug -c one-liner. If you need to verify a secret resolved correctly, hash or fingerprint it instead.

See conventions.md#secrets for the demagify magic-string list and the rule's full rationale.

Read-only commands — useful flag combinations

The fork's AGENTS.md documents the canonical safety envelope. These are the flag combinations agents reach for most often in this repo:

Want to …	Run
Sanity-check the whole repo (parse + cross-cutting hooks)	`bw test` (defaults to `-HIJKMSp`)
Exercise reactors and item-graph for one node	`bw test <node>` (defaults to `-IJKMp`)
Same, but every node that has a given bundle	`bw test bundle:<name>`
Print one metadata key for one node	`bw metadata <node> -k <a/b>` (repeat `-k` for more)
Show where each metadata value comes from	`bw metadata <node> -b`
Resolve Faults (vault values) into the dump	`bw metadata <node> -f` — may print secrets, avoid
List a node's items, with the bundle that defines each	`bw items <node> --blame`
Preview a rendered file's content	`bw items <node> file:<path> -f`
Verify against the live host, scoped to one bundle	`bw verify <node> -o bundle:<name>`
Hash metadata only (faster than full config hash)	`bw hash <node> -m`
Inspect the data backing a hash	`bw hash <node> -d`

bw test, bw verify, bw nodes, bw metadata all share a target- selector grammar: bare node name, group name, bundle:<name>, !bundle:<name>, or "lambda:node.metadata_get('foo/bar', 0) < 3".

3.4 KiB Raw Blame History