Hi everyone,
I’d like to share td-cli, an open-source CLI tool that connects a live TouchDesigner session to the terminal.
What is it?
td-cli is a Go-based command-line tool that talks to a running TouchDesigner project over HTTP. You can inspect operators, change
parameters, execute Python, capture screenshots, apply GLSL shaders, and build entire networks — all from the terminal.
Why?
Two reasons:
- For artists — Sometimes you want to script things quickly, iterate on GLSL shaders from your editor, batch-set parameters, or
inspect a complex network without clicking through every node. td-cli gives you a fast, scriptable workflow alongside the visual
editor. - For AI agents — This was originally built as an execution layer for LLM-driven creative coding. An agent (like Claude or
Codex) reasons about what to build, and td-cli executes it inside a live TD session. It includes a harness system for observe →
verify → rollback loops, so the agent can iterate safely.
Key Features
- Operator management — create, delete, copy, move, search, wire/unwire operators
- Parameter control — get/set values, expressions, pulse, import/export
- Python execution — run inline code or .py files inside TD, with --verify and --screenshot flags
- Data access — read/write DATs, sample CHOPs/SOPs/POPs, read table cells
- GLSL shader templates — apply shaders to GLSL TOPs from the terminal
- Harness (agent loop) — observe state, run assertions, apply changes with automatic rollback
- Offline docs — search operator docs and Python API reference without leaving the terminal
- Auto-discovery — finds running TD instances via heartbeat files
How it works
Terminal / AI Agent
↓
td-cli (Go binary)
↓
HTTP → TD Web Server DAT + Python handler
Example: Build an audio-reactive scene from the terminal
td-cli status # check connection
td-cli exec -f td/fui_scene.py
–verify /project1
–screenshot /project1/out # execute + verify + preview
td-cli par set /project1/ctrl Bassgain 12.0 # tweak parameters live
td-cli screenshot /project1/out -o preview.png # capture output
Links
- GitHub: GitHub - 0dot77/td-cli: TouchDesigner CLI for Claude Code — control TouchDesigner with natural language · GitHub
- License: MIT
Feedback, issues, and PRs are welcome. It’s still evolving — the harness and shader template systems are relatively new.