CT CLI

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

bash
1deno task ct --help           # Top-level commands
2deno task ct piece --help     # Piece operations
3deno task ct check --help     # Type checking

Environment Setup

Identity key (required for most operations):

bash
1ls -la claude.key              # Check for existing
2
3# For local dev: derive key matching toolshed's "implicit trust" identity
4deno run -A packages/cli/mod.ts id derive "implicit trust" > claude.key
5
6# For a fresh random key (e.g., against production):
7deno 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):

bash
1export CT_API_URL=http://localhost:8000  # or https://toolshed.saga-castor.ts.net/
2export CT_IDENTITY=./claude.key

Experimental flags (must be set on both servers AND CLI commands):

bash
1# Pass experiment env vars to CLI commands:
2EXPERIMENTAL_CANONICAL_HASHING=true \
3EXPERIMENTAL_RICH_STORABLE_VALUES=true \
4deno 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

Check Command Flags

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

Common usage:

bash
1deno task ct check pattern.tsx              # Compile + execute (quiet on success)
2deno task ct check pattern.tsx --no-run     # Type check only (fast)
3deno task ct check pattern.tsx --no-check   # Skip types, just execute
4deno task ct check pattern.tsx --show-transformed  # Debug compiler transforms
5deno task ct check pattern.tsx --verbose-errors     # Detailed error context

Core Workflow: setsrc vs new

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

bash
1# First time only
2deno task ct piece new pattern.tsx ...
3# Output: Created piece bafyreia... <- Save this ID!
4
5# ALL subsequent iterations
6deno 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:

bash
1# Strings need nested quotes
2echo '"hello world"' | deno task ct piece set ... title
3
4# Numbers are bare
5echo '42' | deno task ct piece set ... count
6
7# Objects
8echo '{"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.

bash
1# After setting data:
2echo '[...]' | deno task ct piece set --piece ID expenses ...
3deno task ct piece step --piece ID ...  # Required!
4deno task ct piece get --piece ID totalSpent ...
5
6# After calling a handler:
7deno task ct piece call --piece ID addItem '{"title": "Test"}'
8deno task ct piece step --piece ID ...  # Required!
9deno task ct piece inspect --piece ID ...

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

bash
1# 1. Deploy
2deno task ct piece new pattern.tsx -i key -a url -s space
3# 2. Call a handler
4deno task ct piece call --piece ID handlerName '{"arg": "value"}' ...
5# 3. Step to process
6deno task ct piece step --piece ID ...
7# 4. Inspect result
8deno task ct piece inspect --piece ID ...
9# 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

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