tldraw canvas operator

tldraw canvas operator

Use this skill for tasks involving open tldraw Desktop files. The desktop app exposes a local HTTP server that can list documents, inspect canvas state, capture screenshots, execute JavaScript against a live editor, and expose live script files for durable behavior.

Server

The default server is http://localhost:7236. If that port is not active, read the port from /Users/elianiva/Library/Application Support/tldraw/server.json.

A clean quit removes server.json; the next launch rewrites it. It also records pid and startedAt, so if the file is present but requests to its port fail, treat it as stale (the app quit uncleanly) — the app is not running.

Every request except GET / and /readme needs the per-launch token from that same server.json, sent as -H "authorization: Bearer <token>".

If the server's base URL and bearer token are already in your context — the app injects them at subagent launch when its agent hook is installed — use those literal values directly, or just call the installed tq helper (below). The rest of this section is the fallback for when neither is in hand.

Each Bash tool call runs in a fresh shell — exported env vars do NOT persist between calls. A TLDRAW_TOKEN you export in one call is empty in the next, so the request sends authorization: Bearer with no token and 401s. "Export once and reuse" does not work here — re-establish the port and token on every call. Read them together at the top of each call (both stay fixed for the app's lifetime, so re-reading is cheap):

PORT=$(jq -r .port '/Users/elianiva/Library/Application Support/tldraw/server.json'); TOKEN=$(jq -r .token '/Users/elianiva/Library/Application Support/tldraw/server.json')
# use as:  http://localhost:$PORT/...   -H "authorization: Bearer $TOKEN"

Helper: tq

A ready-made helper ships with this skill at "$HOME/skills/tldraw-offline/tq". Invoke it as sh "$HOME/skills/tldraw-offline/tq" <METHOD> <path> [body] — it re-reads the port and token from server.json itself on every call, so you never handle the token or the fresh-shell env problem. A body starting with { is sent as JSON; anything else as raw text/plain:

sh "$HOME/skills/tldraw-offline/tq" POST /api/search '{"code":"return await api.getDocs()"}'
sh "$HOME/skills/tldraw-offline/tq" POST /api/doc/DOC_ID/exec 'return editor.getCurrentPageShapes().length'
sh "$HOME/skills/tldraw-offline/tq" GET  /api/doc/DOC_ID/script-status

If tq is missing (an older install), fall back to raw curl with the PORT/TOKEN reads shown above. The raw-curl examples below stay in explicit form so each request is visible; translate any to sh "$HOME/skills/tldraw-offline/tq" <METHOD> <path> [body].

curl -s http://localhost:7236/readme

Core endpoints