cf

CF CLI

The cf CLI is the command-line interface for Common Fabric. Use --help for current commands:

deno task cf --help           # Top-level commands
deno task cf piece --help     # Piece operations
deno task cf check --help     # Type checking

Invocation Paths

Three ways to run the CLI, in order of preference. All run from source, so they always match the working tree:

1. cf (via bin/cf) — a plain cf backed by source. Already on PATH under mise; otherwise deno task install-cf. Works from any cwd, and shell completion requires a cf on PATH. It runs whichever checkout you are standing in (nearest one walking up, or a host's vendor/labs), not the one it was installed from — set CF_LABS_ROOT to override when your cwd cannot say what you mean, and run cf which to see which CLI would run and why. See "Which checkout runs" in packages/cli/README.md.

2. deno task cf ... — works from any directory inside the repo (the launcher resolves the repo root itself and runs the CLI from your invoking cwd). Deno prints a one-line Task cf ... echo to stderr; silence it with deno -q task cf .... stdout stays clean, so redirection is safe.

3. deno run -q -A packages/cli/mod.ts ... — repo-root-relative; only works with the repo root as cwd. The -q suppresses Deno's own warnings (e.g. the npm "Ignored build scripts" banner).

Do not put dist/cf on your PATH. deno task build-binaries cf still produces it, and CI uses it (a CI run never edits the source it was built from), but there is no invalidation story for a working tree you are actively editing: nothing compares the binary against its sources, so it silently serves stale behavior after a git pull or a local edit. See "Why not dist/cf" in packages/cli/README.md, and the "FUSE mount wrapper mismatch" entry below for what this looks like when it bites.

Output Conventions (scripts & agents)

• stdout carries command output only; hints, tips and diagnostics go to stderr. piece get prints JSON, with no ANSI to strip, and represents an absent value as null.
• ANSI colors are emitted only when stdout is a TTY. Force off with --no-color or NO_COLOR=1; force on (e.g. through a pager) with FORCE_COLOR=1. (cf view keeps its own --color flag.)
• -q/--quiet (on piece/wish subcommands) suppresses hints and next-step blocks on stderr. To also drop runtime warnings, add --log-level error (-q deliberately leaves the log floor alone — scripts parse those warnings).
• piece call payloads: inline JSON argument, - to read stdin (echo '{...}' | cf piece call ... handler -), a bare pipe with no payload argument, or schema-derived flags after --. Empty stdin fails loudly.
• A piece get path that doesn't resolve is a data error: one-line message on stderr, exit 1 (no usage screen). A piece link that fails validation (missing source/target piece or path) reports the same way. So does a piece get path that lands on a handler verb: reading a stream refuses — read data, call verbs. A root verb's refusal points at cf piece call; a nested verb is not directly callable, so it points at reading the parent object or cf piece verbs. The verb's parent object still reads, and tool bindings read as data.

Environment Setup

Identity key (required for most operations):

ls -la cf.key                  # Check for existing

# Never overwrite an existing key file — existing identity-scoped data
# becomes invisible under a new identity.

# Default: a fresh, UNIQUE key. Use this for normal pattern dev and for any
# server (local, shared, or remote).
deno run -A packages/cli/mod.ts id new > cf.key

# To match a browser identity registered with a recovery phrase:
deno run -A packages/cli/mod.ts id from-mnemonic -- phrase.txt > cf.key

# To reproduce a key from your OWN secret passphrase (unique to you; pass via
# file or stdin to keep it out of shell history):
deno run -A packages/cli/mod.ts id derive -- passphrase.txt > cf.key

Both id derive and id from-mnemonic accept the secret three ways: as a file (-- <file>), on stdin (-, or no argument), or as an inline positional argument. Prefer a file or stdin for real secrets — an inline argument is visible in shell history and to other processes via ps. A single trailing newline is stripped from file/stdin input, so echo/editor input matches the equivalent inline value.

Note: id derive (passphrase) and id from-mnemonic (BIP-39 phrase) use different derivations and produce different DIDs from the same text. Use from-mnemonic to match browser mnemonic login; see docs/features/shared-identity.md.

Redirecting stdout (as above) is safe through any invocation path: the deno task echo and all Deno/CLI diagnostics go to stderr, so deno task cf id new > cf.key produces a clean key file.

Environment variables (avoid repeating flags):

export CF_API_URL=http://localhost:8000  # local dev default; only target a remote instance when the task explicitly requires it — remote set/rm/setsrc mutate shared state
export CF_IDENTITY=./cf.key

Identity visibility footgun: If CLI and browser use different DIDs, the same piece should still load and unscoped/PerSpace data should remain visible, but PerUser, PerSession, favorites, drafts, and home-space state may look empty or default. For identity-sensitive local work, use one key everywhere — generate it with id new and import the CLI PKCS8/PEM key in the browser via Import CLI Key. See docs/features/shared-identity.md.

Experimental flags must be set as env vars on both servers AND CLI commands. See docs/development/EXPERIMENTAL_OPTIONS.md for available flags.

Local servers: See docs/development/LOCAL_DEV_SERVERS.md

Quick Command Reference

Check Command Flags

deno task cf check compiles and evaluates patterns. Key flags:

--json, --show-transformed, and --pattern-json are mutually exclusive. Each mode waits for every input to succeed before it writes to stdout. Errors go to stderr and leave stdout empty.

Common usage:

deno task cf check pattern.tsx              # Compile + execute (quiet on success)
deno task cf check pattern.tsx --no-run     # Type check only (fast)
deno task cf check pattern.tsx --no-check   # Skip types, just execute
deno task cf check pattern.tsx --json       # Structured compiled output
deno task cf check pattern.tsx --show-transformed  # Debug compiler transforms
deno task cf check pattern.tsx --verbose-errors     # Detailed error context

Core Workflow: setsrc vs new

Critical pattern: After initial deployment, use setsrc to iterate:

# First time only
deno task cf piece new pattern.tsx ...
# Output: Created piece bafyreia... <- Save this ID!

# ALL subsequent iterations
deno task cf piece setsrc pattern.tsx --piece bafyreia... ...

Why: new creates duplicate pieces. setsrc updates in-place.

setsrc normally rejects incompatible argument/result schema changes and retained links whose durable contracts no longer fit. For an intentional breaking migration, --dangerously-allow-incompatible-schema bypasses those compatibility proofs. new accepts the same flag for deploy-script symmetry, though a fresh piece has no predecessor schema to compare.

Source-file writes through cf fuse mount hit the same update gate. Mount with --dangerously-allow-incompatible-schema when those writes are part of the same intentional breaking migration.

Source location metadata

The local-source deployment commands piece new, piece setsrc, and custom piece set-home accept --root plus --repository. Use the repository checkout root for --root; this preserves source.entry as a path inside the repository. --repository is stored exactly as supplied in source.repository and is never inferred from Git configuration. On setsrc, omitting --repository preserves the existing value; supplying it replaces the value. piece inspect --json and piece ls --json expose the resulting structured source locator.

JSON Input Format

All values to set and call must be valid JSON:

# Strings need nested quotes
echo '"hello world"' | deno task cf piece set ... title

# Numbers are bare
echo '42' | deno task cf piece set ... count

# Objects
echo '{"name": "John"}' | deno task cf piece set ... user

piece get and wish always print JSON. Both accept a redundant --json so callers can request the format explicitly.

piece get --filter accepts a jq-inspired predicate over array items: paths, JSON literals, comparisons, and/or/not, and parentheses. Only false and null are falsey; stored undefined is treated like a missing value and is also falsey. Non-array inputs are rejected. --schema projects output from a comma-separated field list, an inline JSON Schema, or @schema.json; concise fields apply per item for arrays, while JSON Schema describes the whole output. In an array-item projection, a typed scalar leaf that does not match stored data is omitted rather than reported as an error; prefer true leaves unless type filtering is intentional. Concise dotted paths follow declared source schemas through nested arrays: comments.body selects body from every comment and drops its siblings. Source-declared nullable items and properties remain null. If a present source cannot materialize the transform, the command exits nonzero with an explicit "not JSON null" error; an absent optional source retains the ordinary successful null response. If the source schema does not identify a nested container, concise projection still applies its field mask across encountered arrays to prevent sibling disclosure; use an explicit schema for a fixed output contract. The two flags compose as filter-then-project. Both run through runtime filter/map/lift nodes, which construct projected values from source-schema-selected reads, so CFC behavior is the same as a computed pattern expression. Source schema metadata is authoritative; projection schemas cannot supply ifc, asCell, scope, or default. See packages/cli/README.md for the exact syntax and supported schema subset.

For piece call, options before the callable name configure piece call. Arguments after the callable name configure the invoked handler or tool. The JSON forms match cf exec:

# Complete input as an inline JSON value
deno task cf piece call --piece ID search --json '{"query":"milk"}'

# Complete input from stdin
printf '%s' '{"query":"milk"}' |
  deno task cf piece call --piece ID search --json

# Machine-readable callable schema
deno task cf piece call --piece ID search --help --json

# Schema-derived input flags
deno task cf piece call --piece ID search -- --query milk

A single positional JSON value after the callable is also accepted. Use -- --json-file <path> to read JSON from a file. Handler confirmations move to stderr when JSON input is selected, so stdout remains available for JSON tool results. Errors always go to stderr.

Gotcha: Always step After set or call

Neither piece set nor piece call triggers recomputation automatically. You must run piece step after either one to get fresh computed values. When the value is session-scoped, use piece get --step so recomputation and the read happen in the same CLI session; a separate piece step process cannot carry session-local materialization into the following piece get process.

# After setting data:
echo '[...]' | deno task cf piece set --piece ID expenses ...
deno task cf piece step --piece ID ...  # Required!
deno task cf piece get --piece ID totalSpent ...

# Equivalent one-session read (required for session-scoped computed output):
deno task cf piece get --piece ID totalSpent --step ...

A path-less piece get (whole result) degrades outputs it cannot reach — values living in another session's/user's scope are simply absent from the returned object rather than voiding the whole read. Use --step when you need those members materialized in your own session.

# After calling a handler:
deno task cf piece call --piece ID addItem '{"title": "Test"}'
deno task cf piece step --piece ID ...  # Required!
deno task cf piece inspect --piece ID ...

Handler testing workflow (deploy → call → step → inspect):

# 1. Deploy
deno task cf piece new pattern.tsx -i key -a url -s space
# 2. Call a handler
deno task cf piece call --piece ID handlerName '{"arg": "value"}' ...
# 3. Step to process
deno task cf piece step --piece ID ...
# 4. Inspect result
deno task cf piece inspect --piece ID ...
# 5. Repeat 2-4 for each handler

See docs/common/workflows/handlers-cli-testing.md for the full workflow and docs/development/debugging/cli-debugging.md for debugging.

Troubleshooting

FUSE mount wrapper mismatch

On some local setups, the installed cf wrapper (for example dist/cf) can lag behind the source CLI and reject newer fuse mount flags such as -s/--space, even when deno task cf fuse mount --help supports them.

Symptom:

cf fuse mount /tmp/cf -s my-space
# error: Unknown option "-s"

Fix: rebuild the binary (deno task build-binaries --cli-only), or use the source CLI through the repo task wrapper (works from any directory inside the repo):

export CF_IDENTITY=./cf.key
export CF_API_URL=http://localhost:8000

deno task cf fuse mount /tmp/cf -s my-space

This matters because preconnecting the space is required for writable FUSE mounts; auto-discovered spaces may appear writable but silently drop writes.

References

• packages/patterns/system/default-app.tsx - System pieces (pieceRegistry lives here)
• docs/common/workflows/handlers-cli-testing.md - Handler testing
• docs/development/debugging/cli-debugging.md - CLI debugging