ct
Guide for using the ct (CommonTools) binary to interact with charms,
SKILL.md
Full skill instructions
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 charm --help # Charm operations
deno task ct check --help # Type checking
Environment Setup
Identity key (required for most operations):
ls -la claude.key # Check for existing
deno task ct id new > claude.key # Create if missing
Environment variables (avoid repeating flags):
export CT_API_URL=http://localhost:8000 # or https://toolshed.saga-castor.ts.net/
export CT_IDENTITY=./claude.key
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 charm new pattern.tsx -i key -a url -s space |
| Update existing | deno task ct charm setsrc pattern.tsx --charm ID -i key -a url -s space |
| Inspect state | deno task ct charm inspect --charm ID ... |
| Get field | deno task ct charm get --charm ID fieldPath ... |
| Set field | echo '{"data":...}' | deno task ct charm set --charm ID path ... |
| Call handler | deno task ct charm call --charm ID handlerName ... |
| Trigger recompute | deno task ct charm step --charm ID ... |
| List charms | deno task ct charm ls -i key -a url -s space |
| Visualize | deno task ct charm map ... |
Core Workflow: setsrc vs new
Critical pattern: After initial deployment, use setsrc to iterate:
# First time only
deno task ct charm new pattern.tsx ...
# Output: Created charm bafyreia... <- Save this ID!
# ALL subsequent iterations
deno task ct charm setsrc pattern.tsx --charm bafyreia... ...
Why: new creates duplicate charms. 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 charm set ... title
# Numbers are bare
echo '42' | deno task ct charm set ... count
# Objects
echo '{"name": "John"}' | deno task ct charm set ... user
Gotcha: Stale Computed Values
charm set does NOT trigger recompute. Run charm step after:
echo '[...]' | deno task ct charm set --charm ID expenses ...
deno task ct charm step --charm ID ... # Required!
deno task ct charm get --charm ID totalSpent ...
See docs/development/debugging/cli-debugging.md for debugging patterns.
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/restart-local-dev.sh --force |
References
packages/patterns/system/default-app.tsx- System charms (allCharms list lives here)docs/common/workflows/handlers-cli-testing.md- Handler testingdocs/development/debugging/cli-debugging.md- CLI debugging