CT CLI The ct binary is the CLI for CommonTools. Use --help for current commands: deno task ct --help

Top-level commands

deno task ct piece --help

Piece operations

deno task ct check --help

Type checking

Environment Setup Identity key (required for most operations): ls -la claude.key

Check for existing

For local dev: derive key matching toolshed's "implicit trust" identity

deno run -A packages/cli/mod.ts id derive "implicit trust"

claude.key

For a fresh random key (e.g., against production):

deno run -A packages/cli/mod.ts id new

claude.key IMPORTANT: Do NOT use deno task ct id new > file — the deno task wrapper prints ANSI-colored preamble to stdout, which pollutes the key file. Always use deno run -A packages/cli/mod.ts when redirecting output. Environment variables (avoid repeating flags): export CT_API_URL = http://localhost:8000

or https://toolshed.saga-castor.ts.net/

export CT_IDENTITY = ./claude.key Experimental flags (must be set on both servers AND CLI commands):

Pass experiment env vars to CLI commands:

EXPERIMENTAL_CANONICAL_HASHING

true

\

EXPERIMENTAL_RICH_STORABLE_VALUES

=

true

\

deno task ct piece new pattern.tsx

..

.

See

docs/development/EXPERIMENTAL_OPTIONS.md

for all available flags.

Local servers

See docs/development/LOCAL_DEV_SERVERS.md Quick Command Reference Operation Command Type check deno task ct check pattern.tsx --no-run Deploy new deno task ct piece new pattern.tsx -i key -a url -s space Update existing deno task ct piece setsrc pattern.tsx --piece ID -i key -a url -s space Inspect state deno task ct piece inspect --piece ID ... Get field deno task ct piece get --piece ID fieldPath ... Set field echo '{"data":...}' | deno task ct piece set --piece ID path ... Call handler deno task ct piece call --piece ID handlerName ... Trigger recompute deno task ct piece step --piece ID ... List pieces deno task ct piece ls -i key -a url -s space Visualize deno task ct piece map ... Check Command Flags deno task ct check compiles and evaluates patterns. Key flags: Flag Purpose --no-run Type check only, don't execute --no-check Execute without type checking --show-transformed Show the transformed TypeScript after compilation --verbose-errors Show original TS errors alongside simplified hints --pattern-json Print the evaluated pattern export as JSON --output Store compiled JS to a file --main-export Select non-default export (default: "default" ) --filename Override filename for source maps Common usage: deno task ct check pattern.tsx

Compile + execute (quiet on success)

deno task ct check pattern.tsx --no-run

Type check only (fast)

deno task ct check pattern.tsx --no-check

Skip types, just execute

deno task ct check pattern.tsx --show-transformed

Debug compiler transforms

deno task ct 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 ct piece new pattern.tsx .. .

Output: Created piece bafyreia... <- Save this ID!

ALL subsequent iterations

deno task ct piece setsrc pattern.tsx --piece bafyreia .. . .. . Why: new creates duplicate pieces. setsrc updates in-place. JSON Input Format All values to set and call must be valid JSON:

Strings need nested quotes

echo '"hello world"' | deno task ct piece set .. . title

Numbers are bare

echo '42' | deno task ct piece set .. . count

Objects

echo '{"name": "John"}' | deno task ct piece set .. . user 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.

After setting data:

echo '[...]' | deno task ct piece set --piece ID expenses .. . deno task ct piece step --piece ID .. .

Required!

deno task ct piece get --piece ID totalSpent .. .

After calling a handler:

deno task ct piece call --piece ID addItem '{"title": "Test"}' deno task ct piece step --piece ID .. .

Required!

deno task ct piece inspect --piece ID .. . Handler testing workflow (deploy → call → step → inspect):

1. Deploy

deno task ct piece new pattern.tsx -i key -a url -s space

2. Call a handler

deno task ct piece call --piece ID handlerName '{"arg": "value"}' .. .

3. Step to process

deno task ct piece step --piece ID .. .

4. Inspect result

deno task ct 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 Issue Fix Commands hang Check Tailnet connection for *.ts.net URLs Permission denied chmod 600 claude.key JSON parse error Check nested quotes, no trailing commas Local servers not responding ./scripts/check-local-dev.sh then ./scripts/restart-local-dev.sh --force References packages/patterns/system/default-app.tsx - System pieces (allCharms list lives here) docs/common/workflows/handlers-cli-testing.md - Handler testing docs/development/debugging/cli-debugging.md - CLI debugging