Skip to main content

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.

OverrideEffect
TFDESIGN_DATA_DIRRelocate the data root
OD_DATA_DIRSame, for existing workflows
TFDESIGN_DAEMON_URL / OD_DAEMON_URLDefault daemon URL
--daemon-urlAttach 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
FlagMeaning
--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|jsonInteractive terminal, or NDJSON
--daemon-url <url>Attach to a specific daemon
--no-bootNever boot a private daemon
--mirror-root <dir>Mirror project files into <dir>/<project-slug>/
--openOpen 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
FlagMeaning
<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 jsonNDJSON events, same contract as run
--mirror-root <dir>Mirror project files afterwards
--conversation <id>Continue a specific conversation
--max-rounds <n>Round cap
--model / --agentNested 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:

FormatRequiresOn failure
pdfpython3 onlyExit 4 with the interpreter message
pptxpython3 + python-pptx + PillowExit 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​

FlagMeaning
--surfaceimage · video · audio (required)
--modelRegistered model id (required)
--projectProject id; auto-resolved from OD_PROJECT_ID
--promptGeneration prompt; for speech, the text to read
--outputFilename under the project (auto-named if omitted)
--aspect1:1 16:9 9:16 4:3 3:4
--lengthVideo seconds, clamped to the model's maxDurationSec
--durationAudio only — rejected on speech
--voiceProvider voice id
--audio-kindspeech is the only accepted value
--imageProject-relative reference image (image-to-video)
--prompt-influence0–1
--loopGIF / looping video
--languageSpeech language hint
--composition-dirhyperframes-html only — project-relative composition directory
--daemon-urlDefault 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​

FlagMeaning
--modelA model that advertises i2v
--segmentRepeatable shot prompt; 2–8 shots
--aspect / --length / --prompt-influenceApplied to every shot
--outputFinal 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"
FlagApplies toMeaning
--titlecreateDisplay title (required)
--body / --body-filecreate, updateDESIGN.md source; file wins
--summarycreate, updateOne-line summary
--categorycreate, updateCategory label (default Custom)
--surfacecreate, updateweb | image | video | audio
--statuscreate, updatedraft | published
--source-notescreateURL to derive a starter spec from
--format jsonallOne 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​

VariableUsed byPurpose
OD_DAEMON_URL / TFDESIGN_DAEMON_URLall clientsDaemon base URL
OD_PROJECT_IDmedia, runInjected by the daemon at agent spawn
OD_NODE_BINagents, skillsAbsolute path to the runtime that started the daemon
OD_BINagents, skillsAbsolute path to the CLI script
OD_PROJECT_DIRagentsThe project's files folder (agent cwd)
OD_TOOL_TOKENskills files/read/runRun-scoped tool token
OD_DATA_DIR / TFDESIGN_DATA_DIRdaemon, runRelocate all runtime data
OD_MEDIA_CONFIG_DIRdaemonRelocate only media-config.json
OD_RESOURCE_ROOTpackaged daemonSkills / design-systems / craft root
OD_PORTdaemonListen port (default 7456)
OD_BIND_HOSTdaemonBind address (default 127.0.0.1)
The recommended invocation form

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​

CodeMeaning
0Success
2Usage error — bad flag, missing argument
3Daemon unreachable (or --no-boot and no match, or data-root mismatch)
4Request or run failed
5In run: form left unanswered (stdin EOF). In media: provider failure produced a stub
130Canceled 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'