CLI Reference
The tfdesign binary is the programmatic front door to the whole workspace. Install it globally:
npm install -g @toothfairyai/tfdesign
The package also installs a legacy od alias pointing at the same script. Help text always says tfdesign.
Usage:
tfdesign [--port <n>] [--host <addr>] [--no-open]
Start the local daemon and open the web UI.
tfdesign run [brief..] [-] [options]
Run a design task headless through the daemon.
tfdesign export <pptx|pdf> --project <id> [options]
Convert an existing project artifact.
tfdesign projects <list|show <id>>
tfdesign skills <list|show <id>|files <id>|read <id> <path>|run <id> <script> [args...]>
tfdesign design-systems <list|show <id>|files <id>|create|update <id>|delete <id>>
tfdesign files <versions|version-read|version-restore>
tfdesign media <generate|wait|sequence>
tfdesign serve [--port <n>] [--host <addr>]
tfdesign mcp [--daemon-url <url>]
tfdesign mcp skill-tools
tfdesign mcp live-artifacts
tfdesign tools live-artifacts <create|list|update|refresh>
tfdesign tools connectors <list|execute>
Location inheritance
This is the single most important behaviour to understand.
run, export, projects, skills, and design-systems resolve their data root as <cwd>/.tfdesign. A daemon already listening on the default URL is used only when its health payload reports the same data root. Anything else gets a private daemon booted in-process on an ephemeral port, rooted here, which shuts down when the command finishes.
you run tfdesign in ~/work/foo
│
├── daemon at :7456 rooted at ~/work/foo ? ── yes ──► attach
│
└── no ──► boot a private daemon rooted at ~/work/foo/.tfdesign
(ephemeral port, dies when the command ends)
That is what makes agent delegation predictable: a coding agent running in a repo always gets that repo's design state, never a shared global workspace.
| Override | Effect |
|---|---|
TFDESIGN_DATA_DIR | Relocate the data root |
OD_DATA_DIR | Same, for existing workflows |
TFDESIGN_DAEMON_URL / OD_DAEMON_URL | Default daemon URL |
--daemon-url | Attach deliberately to a specific daemon |
--no-boot disables the private-daemon fallback: if no matching daemon is running, the command fails with exit code 3 instead of booting one.
tfdesign run
tfdesign run "A pricing page for Insight, three tiers, FAQ"
tfdesign run --name "Q3 deck" --design-system stripe "Board deck"
tfdesign run --project q3-deck "Add a hiring slide"
echo "A weekly update deck" | tfdesign run --skill simple-deck
| Flag | Meaning |
|---|---|
--project <id|name> | Continue an existing project (default: create) |
--conversation <id> | Continue a specific conversation |
--name <name> | Name a new project (default: derived from the brief) |
--skill <id> | Bind a skill |
--design-system <id> | Bind a design system |
--kind <kind> | image · video · audio · web · deck · document · prototype · template |
--agent <id> | Nested agent id (default tfcode) |
--model <id> | Model for the nested agent |
--format default|json | Interactive terminal, or NDJSON |
--daemon-url <url> | Attach to a specific daemon |
--no-boot | Never boot a private daemon |
--mirror-root <dir> | Mirror project files into <dir>/<project-slug>/ |
--open | Open the preview URL when done |
--max-rounds <n> | Question-form round cap (default 25) |
--kind is not cosmetic. Only a media kind routes the agent to the media generation contract; a media brief without --kind image silently produces a web artifact.
Unknown --kind values throw rather than defaulting, so a typo cannot quietly create the wrong project.
Brief input
tfdesign run "brief as arguments"
tfdesign run - # read all of stdin (default format)
echo "brief" | tfdesign run
In --format json mode the brief is the first stdin line, and stdin stays open for answer lines.
Machine contract (--format json)
NDJSON on stdout, one event per line:
{"type":"run_start","project":{…},"conversationId":"…","created":true,"daemonUrl":"…","booted":false,"dataRoot":"…","projectUrl":"…","mirrorRoot":null}
{"type":"round_start","round":1}
{"type":"text_delta","round":1,"delta":"…"}
{"type":"tool_use","round":1,"id":"…","name":"Write","input":{…}}
{"type":"round_end","round":1,"status":"succeeded","text":"…"}
{"type":"question_form","round":1,"form":{…}}
{"type":"result","project":{…},"entryFile":"index.html","files":[…],"previewUrl":"…","mirrorPath":"…","mirrored":true,"rounds":3,"finalText":"…"}
{"type":"error","code":"RUN_FAILED","message":"…"}
Answers go to stdin, one line per question_form, only after that event was emitted:
{"formId":"<form id>","answers":{"<question id>":"label" | ["labels"]}}
This is the loop tfcode drives: relay each form to the user's question UI, write the answer back.
tfdesign export
tfdesign export pptx --project q3-deck --font modern-ui
tfdesign export pdf --project q3-deck
| Flag | Meaning |
|---|---|
<pptx|pdf> | Output format (or --format) |
--project <id> | Required — an export never creates a project |
--file <name> | Source HTML (default: the project's entry file) |
--font <id> | Pre-answer the PPTX font question |
--font-override <text> | Extra font instruction |
--format json | NDJSON events, same contract as run |
--mirror-root <dir> | Mirror project files afterwards |
--conversation <id> | Continue a specific conversation |
--max-rounds <n> | Round cap |
--model / --agent | Nested agent overrides |
The command forces --skill to the format's workflow (pptx-svg-export or pdf-export) and runs a dependency preflight before the first round:
| Format | Requires | On failure |
|---|---|---|
pdf | python3 only | Exit 4 with the interpreter message |
pptx | python3 + python-pptx + Pillow | Exit 4 with python3 -m pip install python-pptx Pillow |
Checking first matters: without it, a missing dependency surfaces after every SVG has already been generated.
tfdesign media
tfdesign media generate --surface image --model mystica_vision --prompt "…"
tfdesign media wait <taskId> [--since <n>]
tfdesign media sequence --model sorcerer_motion --segment "…" --segment "…"
generate
| Flag | Meaning |
|---|---|
--surface | image · video · audio (required) |
--model | Registered model id (required) |
--project | Project id; auto-resolved from OD_PROJECT_ID |
--prompt | Generation prompt; for speech, the text to read |
--output | Filename under the project (auto-named if omitted) |
--aspect | 1:1 16:9 9:16 4:3 3:4 |
--length | Video seconds, clamped to the model's maxDurationSec |
--duration | Audio only — rejected on speech |
--voice | Provider voice id |
--audio-kind | speech is the only accepted value |
--image | Project-relative reference image (image-to-video) |
--prompt-influence | 0–1 |
--loop | GIF / looping video |
--language | Speech language hint |
--composition-dir | hyperframes-html only — project-relative composition directory |
--daemon-url | Default OD_DAEMON_URL or http://127.0.0.1:7456 |
Flags are whitelisted: a hallucinated --foo fails immediately rather than being silently dropped while a bogus body reaches the daemon.
--project falls back to OD_PROJECT_ID, which is precisely what the daemon injects when it spawns an agent — so a skill can call this without being told the project.
wait
tfdesign media wait <taskId> --since <n>
Long-polls for up to 25 seconds. Exit 2 means still running — use the emitted nextSince to continue. This is the sanctioned polling primitive; do not loop on sleep.
sequence
| Flag | Meaning |
|---|---|
--model | A model that advertises i2v |
--segment | Repeatable shot prompt; 2–8 shots |
--aspect / --length / --prompt-influence | Applied to every shot |
--output | Final mp4 name |
Requires ffmpeg and ffprobe.
Output
One line of JSON on stdout:
{"file":{"name":"hero.png","size":1843200,"kind":"image","mime":"image/png"}}
Warnings (a clamped length, a provider note) go to stderr. Exit 5 means a provider failure produced a stub file — the agent is instructed to surface that verbatim rather than claim success.
tfdesign skills
tfdesign skills list
tfdesign skills show pptx-svg-export [--body]
tfdesign skills files pptx-svg-export
tfdesign skills read pptx-svg-export SKILL.md
tfdesign skills run pptx-svg-export scripts/svg_to_pptx.py --out deck.pptx
files, read, and run require OD_TOOL_TOKEN — the run-scoped token the daemon injects. They are the CLI fallback when an agent's engine did not mount the skill-tools MCP server.
run flags: --timeout <ms> (default 300000, max 600000), --format json. The command exits with the script's own exit code.
tfdesign design-systems
tfdesign design-systems list
tfdesign design-systems show linear-app
tfdesign design-systems files linear-app
tfdesign design-systems create --title "Acme" --body-file ./DESIGN.md
tfdesign design-systems update "user:acme" --body-file ./acme-v2.md
tfdesign design-systems delete "user:acme"
| Flag | Applies to | Meaning |
|---|---|---|
--title | create | Display title (required) |
--body / --body-file | create, update | DESIGN.md source; file wins |
--summary | create, update | One-line summary |
--category | create, update | Category label (default Custom) |
--surface | create, update | web | image | video | audio |
--status | create, update | draft | published |
--source-notes | create | URL to derive a starter spec from |
--format json | all | One JSON document |
delete refuses a bundled id before the round trip; --yes skips the client-side guard and lets the daemon reject it explicitly.
tfdesign projects
tfdesign projects list
tfdesign projects show <id|name>
Prints id, name, updated timestamp, and entry file. This is how you discover the id for run --project and export --project.
tfdesign files
tfdesign files versions <projectId> <fileName>
tfdesign files version-read <projectId> <fileName> <versionId>
tfdesign files version-restore <projectId> <fileName> <versionId>
Per-file version history. --json prints the raw payload; --prompt <text> attaches a note to a restore.
tfdesign serve
tfdesign serve --port 7600 --host 127.0.0.1
Starts the daemon and web UI without opening a browser. Never returns — the process is the daemon.
tfdesign mcp
See MCP Server.
tfdesign mcp # project access, 31 tools
tfdesign mcp skill-tools # skill side files + script execution
tfdesign mcp live-artifacts # live artifacts + connectors
tfdesign tools
tfdesign tools live-artifacts <create|list|update|refresh>
tfdesign tools connectors <list|execute>
Wrapper commands for the daemon's tool endpoints, for agents that have shell access but no MCP mount.
Environment variables
| Variable | Used by | Purpose |
|---|---|---|
OD_DAEMON_URL / TFDESIGN_DAEMON_URL | all clients | Daemon base URL |
OD_PROJECT_ID | media, run | Injected by the daemon at agent spawn |
OD_NODE_BIN | agents, skills | Absolute path to the runtime that started the daemon |
OD_BIN | agents, skills | Absolute path to the CLI script |
OD_PROJECT_DIR | agents | The project's files folder (agent cwd) |
OD_TOOL_TOKEN | skills files/read/run | Run-scoped tool token |
OD_DATA_DIR / TFDESIGN_DATA_DIR | daemon, run | Relocate all runtime data |
OD_MEDIA_CONFIG_DIR | daemon | Relocate only media-config.json |
OD_RESOURCE_ROOT | packaged daemon | Skills / design-systems / craft root |
OD_PORT | daemon | Listen port (default 7456) |
OD_BIND_HOST | daemon | Bind address (default 127.0.0.1) |
Inside an agent runtime, prefer:
"$OD_NODE_BIN" "$OD_BIN" media generate …
over a bare tfdesign. Packaged desktop installs provide OD_NODE_BIN even when the user has no system node on PATH, and OD_BIN avoids relying on the user's PATH resolving the bin.
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
2 | Usage error — bad flag, missing argument |
3 | Daemon unreachable (or --no-boot and no match, or data-root mismatch) |
4 | Request or run failed |
5 | In run: form left unanswered (stdin EOF). In media: provider failure produced a stub |
130 | Canceled via SIGINT / SIGTERM |
media wait also returns 2 to mean still running, which is why the code is documented in the handoff message rather than treated as a failure.
Common patterns
Headless batch runs
for brief in briefs/*.txt; do
tfdesign run --format json "$(cat "$brief")" --mirror-root ./out
done
Delegate from a coding agent
tfdesign run --format json "A dashboard for our API usage" \
--mirror-root "$PWD/design"
The agent reads question_form events, relays them to the user, writes answers back to stdin, and finally reports previewUrl and mirrorPath.
Check what exists before binding
tfdesign design-systems list --format json | jq -r '.designSystems[].id'
tfdesign skills list --format json | jq -r '.skills[].id'