Advanced CLI workflows

These commands are documented for the current stable Bee release. Run them in the intended checkout. bee --version identifies the installed binary; a different installed version can have different behavior. For the rest of the command surface, see the command reference; for agent-facing reads, see MCP tools.

Retain and inspect an artifact

artifact add copies a UTF-8 source into a private store scoped to the physical checkout. It accepts JSON (the default, validated on ingest) or text, up to 1 MiB per source and 64 retained artifacts per checkout. Reads verify the manifest and exact retained bytes; they do not reread the original file or rerun a command. Use a store owned by the selected Bee instance if you also want its MCP tools to see these artifacts.

# Run in a Git checkout containing reports/results.json.
checkout="$(git rev-parse --show-toplevel)"
artifact_store="$HOME/.bee/artifacts" # default instance; use the selected instance root for a named instance
bee artifact add --root "$checkout" --store "$artifact_store" --file reports/results.json --format json
# Copy the returned id (SHA-256) into artifact_id.
artifact_id='<returned-id>'
bee artifact search --root "$checkout" --store "$artifact_store" --text 'failed' --limit 20 --offset 0 --budget 65536
bee artifact get --root "$checkout" --store "$artifact_store" --id "$artifact_id" --out "$checkout/recovered-results.json"

add returns id, root, sourcePath, sourceSha256, sourceBytes, format, and raw-capture metadata. search performs an ordinal literal line search, across this checkout’s archive or a single --id. It returns schemaVersion, artifactsSearched (archive search), matchedRecords before pagination, offset, nextOffset, and rows; rows identify the artifact, source hash/path, line and text. The single-ID search instead returns artifactId, sourceSha256, operation: "search", matchedRecords, totalRows, and its page. get creates a new output file, then reports status: "recovered", id, sourceSha256, and sourceBytes; it refuses to overwrite an existing file.

Query a retained JSON array, without evaluating code or SQL. The query file is at most 64 KiB. JSON Pointers select the array and row fields; empty arrayPointer selects a top-level array. eq/ne are typed, contains tests text, and exists tests presence. A missing property differs from JSON null; ne matches only present values. countOnly returns no rows, while groupBy requires a scalar pointer. limit is 1–1000 and defaults to 100.

{
  "arrayPointer": "/results",
  "filters": [{"pointer": "/outcome", "operation": "eq", "value": "failed"}],
  "select": ["/name", "/outcome"],
  "offset": 0,
  "limit": 20,
  "maximumOutputBytes": 65536
}

Save that object as query.json, then run:

bee artifact query --root "$checkout" --store "$artifact_store" --id "$artifact_id" --query-file query.json

The result includes schemaVersion, artifactId, sourceSha256, operation: "query", matchedRecords, totalRows, offset, nextOffset, and rows. Search and query fail if the requested complete JSON result exceeds the output budget; they do not silently clip evidence. Sources must be regular files inside the exact Git checkout, not symlinked or hardlinked inputs. The store must remain private. Syntax errors exit 4; refused inputs, missing/corrupt captures, budget failures and cancellation exit 5, with errorCode on stderr.

Encode and decode a JSON representation

representation encode chooses a versioned JSON-value packet, using column representation only when its measured envelope is smaller. It preserves JSON values and number spellings, but not original whitespace or property order. Use artifact recovery when exact original bytes matter.

bee representation encode --file reports/results.json --encoding cl100k_base > packet.json
bee representation decode --file packet.json > decoded.json

o200k_base is the other supported --encoding; the default is cl100k_base. The packet declares its format, encoding, token counts and content. Token counts describe the selected local encoding, not provider billing. Input JSON is limited to 1 MiB. Decode verifies and expands the packet within its own bound; a malformed packet or oversized expansion fails instead of returning partial JSON. These commands read local files and write only their stdout; shell redirection is your explicit file write.

Compress optional prose, then recover the original

Compression is off by default. It is lossy and only accepts text explicitly classified as prose. Do not pass source code, prompts, instructions, mixed packets, legal or exact test evidence. setup is the only operation that installs/downloads a local Python runtime and model; it does not turn compression on. Inspect the runtime and enable it explicitly:

bee compression settings show
bee compression setup --python python3
bee compression doctor
bee compression settings on
bee context compress --input notes.txt --content-kind prose --rate 0.5
# Use originalSha256 from the compression response:
bee compression recover --sha256 '<originalSha256>'

--rate accepts 0.1–0.9. Responses include status, text, originalSha256, optional originalPath/compressedSha256, semanticRisk, local originalTokens/compressedTokens, and runtime measurements where available. Recovery returns status: "recovered", exact text, and verified sha256. Disabled compression returns the original; a successful compressed result still marks semanticRisk: true. Review the recovered text before depending on meaning. The adapter is local and has no implicit cloud fallback. Limits include 64 KiB/8,192 local tokenizer tokens of input and 120 seconds for inference. settings and retained originals live under the selected instance root; these are local writes. Invalid usage exits 4; incomplete runtime/compression/recovery exits 5. See context and provider tools for other ways to reduce selected context.

Preview a C# symbol edit before applying it

symbol uses an existing, fresh C# graph to locate one declaration. Obtain the symbol ID from graph outline and the source file’s SHA-256 from the graph/source evidence. The hash guards against a source change between selection and edit. Put UTF-8 C# replacement text in replacement.txt; a new .cs file inside the checkout would invalidate the graph. Inspect the proposed change:

checkout="$(git rev-parse --show-toplevel)"
bee graph build --json
bee graph outline src/Example.cs --json
shasum -a 256 src/Example.cs # copy the first field as <source-sha256>
bee symbol preview --root "$checkout" --symbol '<symbol-id>' --expected-sha256 '<source-sha256>' \
  --operation replace --replacement-file replacement.txt --budget 65536 --json
# Only after reviewing the preview and confirming the source hash:
bee symbol apply --root "$checkout" --symbol '<symbol-id>' --expected-sha256 '<source-sha256>' \
  --operation replace --replacement-file replacement.txt --budget 65536 --json
bee graph build --json

Operations are replace, insert-before, and insert-after; --replacement-file - reads stdin. preview never writes. apply changes only the verified declaration lines and preserves a UTF-8 BOM. Both return ok, applied, supportedLanguage: "csharp", optional errorCode, and edit details (path, symbolId, graph/source/candidate hashes, operation, byte span, before, after). Apply does not rebuild the graph, compile, or run tests. Replacement input is capped at 64 KiB; source/candidate files at 256 KiB; output budget is 512–262144 bytes, default 65536. An ambiguous symbol, stale graph or hash mismatch refuses the edit. Invalid syntax/input exits 4; refused edits exit 5.

Carry a design export into implementation

design reads HTML, a directory, or ZIP offline. It does not execute embedded scripts. prepare writes a local transfer package for a design provider; it does not upload anything. import retains the complete raw mock and an index. list gives stable element IDs, slice supplies a bounded source/dependency closure for one ID, map records a source-to-implementation link, and verify checks source and mapping integrity. Use a physical path for source/output; on macOS /tmp is a symlink, so this example creates a directory under the home directory.

bee design doctor
demo_dir="$(mktemp -d "$HOME/bee-doc-demo.XXXXXX")"
bee design prepare mock.zip --output "$demo_dir/transfer"
bee design import mock.zip --output "$demo_dir/bundle"
bee design list "$demo_dir/bundle"
bee design slice "$demo_dir/bundle" --id '<id-from-list>' --budget 65536
bee design map "$demo_dir/bundle" --mapping mapping.json
bee design verify "$demo_dir/bundle" --json

For map, mapping.json contains id, absolute target and fixture paths, reuseStrategy (direct-extract, constrained-transform, existing-component, or rebuild-region), and optional route, expectedRevision, and reason; rebuild-region requires a reason. prepare optionally accepts user-supplied --provider-file-limit-bytes and --provider-total-limit-bytes; Bee does not discover a provider’s limits. slice needs --id and accepts a 512–65536-byte budget. Responses use schemaVersion and status; result operations place their data in result, while import reports bundle, revision, file/element/limitation counts and visualAcceptance: false. A slice exposes complete, segments, dependencies, limitations, and omitted counts. Exit 0 means complete, 4 invalid usage, and 5 incomplete/refused. verify checks hashes and dependency closure, not screenshot fidelity or design approval. See design skill for creating the source export.

Capture and compare visual evidence

Visual checks require a separate Node runner. doctor only reports availability; it does not install packages or prove browser readiness. Continue in the same shell so demo_dir still refers to the imported bundle. Export once to a new directory, install its locked dependencies yourself, then draft and complete a spec from the imported design bundle:

bee visual doctor
bee visual export-runner --output "$demo_dir/visual-runner"
cd "$demo_dir/visual-runner" && npm ci
bee visual init --bundle "$demo_dir/bundle" --output "$demo_dir/visual-draft.json"
# Complete the draft's required selectors, runtime profile, fixtures, recipes, and region checks.
bee visual reference --request /absolute/path/reference-request.json --runner-dir "$demo_dir/visual-runner"
bee visual capture --request /absolute/path/capture-request.json --runner-dir "$demo_dir/visual-runner"
bee visual compare --request /absolute/path/compare-request.json --runner-dir "$demo_dir/visual-runner"
bee visual report --request /absolute/path/report-request.json --runner-dir "$demo_dir/visual-runner"

Action	Evidence produced
select	Chooses scenario IDs from specPath, policyPath, and relative changedPaths; reports coverage, but runs zero visual checks.
cache-clean	Previews reference-cache cleanup by default; only an explicit request with remove: true deletes verified Bee-owned cache entries.
reference	Captures the declared design source as the reference; it never uses an application screenshot as a golden.
capture	Captures the running application with explicit web.files hashes and source build/artifact identity; application captures are always fresh.
compare	Checks selected regions, state, fixture, profile, source and artifact identities; writes comparison.json with bounded findings.
report	Verifies existing comparison artifacts and writes a script-free HTML report; it does not upload files.

Reference/capture requests provide absolute specPath and outputDir, optional scenarioIds, and a web source. Capture additionally requires web.files: [{path, sha256}] and source: {sourceId, buildId, artifactSha256}. The exported runner contains exact JSON schemas and a public demo generator for complete request examples.

Its request must be schema version 1 and use absolute paths for path fields; browser capture needs an installed browser or an explicit browserExecutable in its request. --node selects an absolute Node executable; --timeout is 1–300 seconds, default 60. init writes a draft, with requiresCompletion: true and acceptance: false; fill its placeholders before using it as a spec. Runner responses contain schemaVersion, operation, status, exitCode, trusted: false, and acceptance: false. Exit 0 is a runner pass, 3 a visual mismatch, 4 incomplete, and other nonzero results are errors. Evidence authored by the caller is still untrusted; a visual report is diagnostic and needs human review.

Isolate several Bee instances on one machine

The legacy default instance remains at ~/.bee. A named instance has separate bootstrap, database, collaboration space, persona, worker configuration and local state. Map a checkout path and, if needed, a repository remote pattern. Check the actual resolved scope before recording work:

bee instance list --json
bee instance add demo --path /absolute/path/to/checkout --json
bee instance which /absolute/path/to/checkout --json
cd /absolute/path/to/checkout
bee instance show --verify --json
bee instance doctor --json
bee instance env demo --shell zsh

add accepts repeatable --path and --remote; map and unmap change one mapping (--path or --remote). policy --unmatched legacy|hooks-silent|deny controls unmatched paths. exec <name> [--cwd DIR] -- <cmd> runs a child in the selected scope and preserves its exit code, subject to the calling session’s pin. stamp checks/records database ownership; worker-agent renders local worker configuration and writes it only with --write. doctor --scan DIR extends checks; --fix-permissions is an explicit write. remove removes registry routing, not the instance data. sessions prune --older-than DAYS --yes permanently withholds old native session IDs and cannot tell whether a harness process is still using one; treat it as a deliberate cleanup operation.

which is a pin-free path-routing preview; its JSON gives name, reason, matchedPath, matchedRemote, and root. show --verify reports the active instance, including bootstrap and stamp diagnostics. Checkout path alone does not establish the active scope: remote mapping, --instance/BEE_INSTANCE, and the live native session pin can affect it. Conflicts refuse with exit 8 rather than mix data. A named instance’s database and broker credentials must be scoped to that instance to form an actual cross-organization boundary. See configuration and troubleshooting.

Launch an opted-in worker

collaborate launch submits a task to an existing authenticated collaboration session and a node that opted into local worker launch. The receiver controls the executable, arguments, environment, workspace allowlist and capacity. Inspect local policy before submitting; neither this inspection nor a queued request proves a process started.

bee worker profiles --json
bee worker inspect '<profile>' --space '<space>' --workspace '<workspace-key>' --json
BEE_COLLABORATE_SESSION_ID='<joined-session-id>' bee collaborate launch \
  --request '<stable-uuid>' --node '<exact-node-id>' --profile '<profile>' \
  --workspace '<workspace-key>' --prompt-file task.txt --ttl-seconds 300 --json
BEE_COLLABORATE_SESSION_ID='<joined-session-id>' bee collaborate launch-status --request '<stable-uuid>' --json

--prompt-file - reads stdin; task text is bounded to 128 KiB. --ttl-seconds is 5–3600, default 300. Use the same stable UUID to inspect or cancel the intent (launch-cancel --request ...); retrying with a new UUID can create another intent. A successful response includes requestId, scope, nodeId, profile, workspace, state, version, creation/expiry/update times, cancelRequested, and process metadata. nativeBinding: "not_verified", agentOutcome: "not_assessed", and qa: "not_assessed" mean that a launch receipt is not work acceptance. Verify the actual harness session, source files and tests. An uncertain outcome blocks further launch on that node and space; do not bypass it with a second request. See collaboration and plans for session and task tracking.