@kitschpatrol/tldraw-cli

@kitschpatrol/tldraw-cli

A CLI tool for exporting tldraw sketch URLs and local .tldr files to SVG or PNG images.

Table of contents

• Overview
• Installation
• Usage
  • CLI
  • API
  • Common workflows
• Background
• Implementation notes
• The future
• Maintainers
• Contributing
• License

Overview

A CLI app to automate conversion and export of tldraw URLs and .tldr files into SVG or PNG image formats, exposing a number of options along the way. It also provides commands for opening tldraw files in either local or remote instances of the tldraw editor website.

This could be useful in the context of a content publishing pipeline where you want to use a .tldr file (perhaps under version control) as the "source of truth" for assets to be embedded elsewhere, and you don't want to manage the export of that diagram manually.

For .tldr file import support in Vite projects, please see @kitschpatrol/vite-plugin-tldraw.

Installation

Invoke directly:

npx @kitschpatrol/tldraw-cli export some-file.tldr

...or install locally:

npm install --save-dev @kitschpatrol/tldraw-cli

...or install globally:

npm install --global @kitschpatrol/tldraw-cli

Usage

CLI

[!NOTE]
As of version 4.5.0, command line functionality is aliased to both tldraw and tldraw-cli.

The less verbose tldraw command is preferred. The tldraw-cli alias is deprecated and will be removed in the next major version.

Command: tldraw

CLI tools for tldraw.

This section lists top-level commands for tldraw.

Usage:

tldraw <command>

Command	Argument	Description
export	<files-or-urls..>	Export a local tldraw ".tldr" file or a tldraw.com URL to an svg, png, json, or tldr file. Prints the absolute path(s) to the exported image(s) to stdout.
open	[files-or-urls..]	Open a tldraw .tldr file or tldraw.com URL in your default browser with either the official tldraw.com site or a locally-hosted instance of the editor. Call open without an argument to open a blank sketch. Sketches opened via URL with the --local flag will be temporarily copied to the local system, and will not be kept in sync with tldraw.com. This process does not exit until the browser is closed. Warning: Passing a local .tldr file without the --local option will upload and share the sketch on tldraw.com.

Option	Description	Type
--help -h	Show help	boolean
--version -v	Show version number	boolean

See the sections below for more information on each subcommand.

Subcommand: tldraw export

Export a local tldraw ".tldr" file or a tldraw.com URL to an svg, png, json, or tldr file. Prints the absolute path(s) to the exported image(s) to stdout.

Usage:

tldraw export <files-or-urls..>

Positional Argument	Description	Type
files-or-urls	The tldraw sketch to export. May be one or more paths to local .tldr files, or tldraw.com sketch URLs. Accepts a mix of both file paths and URLs, and supports glob matching via your shell. Prints the absolute path(s) to the exported image(s) to stdout. (Required.)	array

Option	Description	Type	Default
--format -f	Output image format.	"png" "svg" "json" "tldr"	"svg"
--output -o	Output image directory.	string	"./"
--name -n	Output image name (without extension).	string	The original file name or URL id is used.
--frames	Export each sketch "frame" as a separate image. Pass one or more frame names or IDs to export specific frames, or pass the flag without the arguments to export all frames. By default, the entire first page is exported with all frames.	array	false
--pages	Export each sketch "page" as a separate image. Pass one or more page names or IDs to export specific page, or pass one or more page index numbers (from 0), or pass the flag without the arguments to export all pages. By default, only the first page is exported.	array	false
--transparent -t	Export an image with a transparent background.	boolean	false
--dark -d	Export a dark theme version of the image.	boolean	false
--padding	Set a specific padding amount around the exported image.	number	32
--scale	Set a sampling factor for raster image exports.	number	1
--strip-style	Remove <style> elements from SVG output, useful to lighten the load of embedded fonts if you intend to provide your own stylesheets. Applies to SVG output only.	boolean	false
--print -p	Print the exported image(s) to stdout instead of saving to a file. Incompatible with --output, and disregards --name. PNGs are printed as base64-encoded strings.	boolean	false
--verbose	Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection.	boolean	false
--help -h	Show help	boolean
--version -v	Show version number	boolean

Subcommand: tldraw open

Open a tldraw .tldr file or tldraw.com URL in your default browser with either the official tldraw.com site or a locally-hosted instance of the editor. Call open without an argument to open a blank sketch. Sketches opened via URL with the --local flag will be temporarily copied to the local system, and will not be kept in sync with tldraw.com. This process does not exit until the browser is closed. Warning: Passing a local .tldr file without the --local option will upload and share the sketch on tldraw.com.

Usage:

tldraw open [files-or-urls..]

Positional Argument	Description	Type
files-or-urls	The .tldr file(s) or tldraw.com sketch URL(s) to open. Omit the argument to open a blank sketch. Supports glob matching via your shell. Prints the URL of the local server to stdout.	array

Option	Description	Type	Default
--local -l	Open the file or URL in a local instance of tldraw, instead of tldraw.com.	boolean	false
--verbose	Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection.	boolean	false
--help -h	Show help	boolean
--version -v	Show version number	boolean

Examples

Basic .tldr file image export

To export the file your-drawing.tldr to an SVG named your-drawing.svg in the current working directory, run the following command. Note that the default output format is SVG, and the default export location is the current working directory.

tldraw export your-drawing.tldr

The file will retain its original name, e.g. your-drawing.svg

Basic tldraw.com image download

tldraw export https://www.tldraw.com/s/v2_c_JsxJk8dag6QsrqExukis4

The tldraw.com URL's id (e.g. v2_c_JsxJk8dag6QsrqExukis4) will be used for the file name.

This is approximately equivalent to clicking the tldraw.com "☰ → Edit → Export As → SVG" menu item.

Export a remote tldraw.com image to a local .tldr file

tldraw export https://www.tldraw.com/s/v2_c_JsxJk8dag6QsrqExukis4 --format tldr

This is approximately equivalent to clicking the tldraw.com "☰ → File → Save a copy" menu item.

Note that using --format tldr with a file path instead of a URL will still send the file through the pipeline, but it's effectively a no-op. (Except perhaps in rare edge cases where tldraw performs a file format version migration).

Export to a specific image / file format

tldraw export your-drawing.tldr --format png

This is approximately equivalent to clicking the tldraw.com "☰ → Edit → Export As → PNG" menu item.

Export with a transparent background

tldraw export your-drawing.tldr --transparent --format png

This is approximately equivalent to checking the tldraw.com "☰ → Edit → Export As → ☐ Transparent" menu item.

Export to a specific destination

tldraw export your-drawing.tldr --output ~/Desktop

Exports to ~/Desktop/your-drawing.svg

Export to a specific destination and filename

tldraw export your-drawing.tldr --output ~/Desktop --name not-your-drawing

Exports to ~/Desktop/not-your-drawing.svg

Export all frames from a tldraw.com URL

tldraw export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames

The exported files will be suffixed with their frame name, e.g.:

v2_c_FI5RYWbdpAtjsy4OIKrKw-frame-1.png v2_c_FI5RYWbdpAtjsy4OIKrKw-frame-2.png v2_c_FI5RYWbdpAtjsy4OIKrKw-frame-3.png

The frame name will be slugified.

It's possible in tldraw to give multiple frames in a single sketch the same name. In these cases, the frame ID is used in addition to the name to ensure unique output file names.

Export a specific frame from a tldraw.com URL

tldraw export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames "Frame 3"

Export multiple frames from a tldraw.com URL

tldraw export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames "Frame 1" "Frame 3"

Export a specific page by name from a tldraw.com URL

tldraw export https://www.tldraw.com/s/v2_c_L_RFQ3mJA_BWHejdH2hlD --pages "Page 3"

Export a specific pages by index from a tldraw.com URL

tldraw export https://www.tldraw.com/s/v2_c_L_RFQ3mJA_BWHejdH2hlD --pages 0 2

Export each pages as its own SVG from a tldraw.com URL

tldraw export https://www.tldraw.com/s/v2_c_L_RFQ3mJA_BWHejdH2hlD --pages

Export to JSON

tldraw export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --format "json"

The .tldr file format is also JSON under the covers, but the --format json flag will yield a slightly different format than --format tldr. --format json is equivalent to what's produced via the tldraw.com "☰ → Edit → Export As → JSON" menu item.

I'm not completely clear on the use-case for this format, but since tldr.com supports it, so too shall tldraw-cli.

Write an SVG to stdout

tldraw export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --print

Open a tldraw.com URL

tldraw open https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw

The remote sketch is copied to a locally-hosted instance of tldraw, which is then opened in your default browser.

API

The tldraw-cli command line functionality is also provided in module form for programmatic use in TypeScript or JavaScript Node projects.

The library exports two async function, tldrawToImage, and tldrawOpen.

tldrawToImage

This mirrors the tldraw export CLI command.

It takes an options argument mirroring the arguments available via the command line. The same default values apply:

 async function tldrawToImage(
  tldrPathOrUrl: string,
  {
    dark?: boolean
    format?: 'svg' | 'png' | 'json' | 'tldr'
    frames?: boolean | string[]
    name?: string
    output?: string
    padding?: number
    pages?: boolean | string[] | number[]
    print?: boolean
    scale?: number
    stripStyle?: boolean
    transparent?: boolean
 }): Promise<string[]>;

The function exports the image in the requested format and returns an array of the output image(s) or file(s).

Generally, a single file is returned — but the string[] return type also accommodates invocations with frame: true where multiple images will be generated.

Assuming you've installed @kitschpatrol/tldraw-cli locally in your project, it may be used as follows:

// tldraw-cli-api-test.ts

import { tldrawToImage } from '@kitschpatrol/tldraw-cli'

// Convert a local file to PNG
const [imagePath] = await tldrawToImage('./some-file.tldr', { format: 'png', output: './' })
console.log(`Wrote image to: "${imagePath}"`)

// Convert a remote tldraw.com URL to SVG
await tldrawToImage('https://www.tldraw.com/s/v2_c_JsxJk8dag6QsrqExukis4')

// Convert all frames from a single tldraw.com URL to separate SVGs
// When the `frames` option is set, the function returns an array
// of resulting file paths, instead of a solitary string
const framePathsArray = await tldrawToImage('https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw', {
  frames: true,
})
console.log(`Wrote frames to: "${framePathsArray}"`)

// Convert a specific frame from a tldraw.com URL to a PNG
await tldrawToImage('https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw', {
  frames: ['Frame 3'],
  format: 'png',
})

// You can also use the frame id instead of the frame name, if you're into that sort of thing
// It will work with or without the `shape:` prefix
await tldrawToImage('https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw', {
  frames: ['shape:x8z3Qf7Hgw4Qqp2AC-eet'],
})

By default, the Node API only logs warnings and errors. If you want to log the equivalent of the --verbose flag from the command line version, then you can set a flag on a logging object exported from the library:

// tldraw-cli-api-verbose-test.ts

import { tldrawToImage, log } from '@kitschpatrol/tldraw-cli'

// this will log extra info
log.verbose = true
await tldrawToImage('https://www.tldraw.com/s/v2_c_JsxJk8dag6QsrqExukis4')

// now we'll only log errors and warnings
log.verbose = false
await tldrawToImage('https://www.tldraw.com/s/v2_c_JsxJk8dag6QsrqExukis4')

tldrawOpen

Mirrors the tldraw open CLI command.

[!CAUTION] Passing a local .tldr file with the location: 'remote' option will upload and share your sketch on tldraw.com.

async function tldrawOpen(
  tldrPathOrUrl?: string,
  options?: Partial<{
    location: 'local' | 'remote'
  }>,
): Promise<{
  browserExitPromise: Promise<ChildProcess>
  openedSketchUrl: string
}>

It's important to note that the returned result includes browserExitPromise, which resolves when the user has completely exited the web browser used to open the tldr file or url.

You must await the browserExitPromise (or somehow keep script's process alive) if you're opening a tldr file with the `location: 'local'`. This prevents the local server from closing prematurely, which would interfere with any server-dependent actions in tldraw.

Example of opening a local file:

import { tldrawOpen } from 'tldraw-cli'

const { browserExitPromise } = await tldrawOpen('./sketch.tldr', {
  location: 'local',
})

// Wait for the browser to close to keep
// the local tldraw instance running!
await browserExitPromise

While opening the file remotely on tldraw.com is more casual:

import { tldrawOpen } from 'tldraw-cli'

await tldrawOpen('./sketch.tldr', {
  location: 'remote',
})

tldrawToShareUrl

async function tldrawToShareUrl(tldrPathOrUrl: string): Promise<string>

Returns a live "share" url for a given local or remote tldraw sketch URL.

[!CAUTION] Passing a local .tldr file to this function will upload and share your local file to tldraw.com.

Common workflows

If you're working with .tldr files and tldraw-cli locally, it's often convenient to automatically export image files from your sketches whenever they've changed.

Depending on your workspace and particularly use-cases, there are several approaches that can work well to trigger re-export on change:

A pure CLI workflow

The chokidar-cli tool (which wraps the Chokidar library) makes quick work of this:

npx chokidar-cli "**/*.tldr" -c "npx @kitschpatrol/tldraw-cli export ${path}"

This will watch for changes to .tldr files anywhere in or below the current directory, and then export an SVG every time they change. Pass additional flags to tldraw-cli export if you need particular export settings.

VS Code tldraw extension workflow

The tldraw extension for VS Code allows you to edit local .tldr files directly from a tab in your editor. This combines well with the File Watcher extension to trigger re-exports after making edits in a tldraw tab:

Install the extensions (assuming you have code in your path):

code --install-extension tldraw-org.tldraw-vscode
code --install-extension appulate.filewatcher

Then configure your workspace's .vscode/settings.json file to include the following:

{
  "filewatcher.commands": [
    {
      "match": "\\.tldr",
      "isAsync": true,
      "cmd": "cd ${workspaceRoot} && npx @kitschpatrol/tldraw-cli export ${file}",
      "event": "onFileChange"
    }
  ]
}

Vite / static-site workflow

If you're using one of the many Vite-powered web frameworks out there, the @kitschpatrol/vite-plugin-tldraw plugin can help you treat .tldr as regular importable / linkable assets in your site by automating conversion to a web-friendly format during both development and production builds of your site.

See the plugin's readme for details, but the gist is that it lets you import and use .tldr files as if they were already SVGs:

import tldrFile from './test-sketch.tldr'

document.body.innerHTML = `<img src="${tldrFile}">`

Will render:

<img src="./test-sketch.svg" />

Background

The potential utility of a tldraw CLI app has received mention a few times.

On GitHub:

• [Feature]: CLI export application #1491
• AWS Lambda-based approach
• Added exporting of shapes and pages as images
• [feature] Copy/Share as PNG

On Discord:

• @jorisjh in #ideas_old
• @Nitsuj in #ideas_old

Implementation notes

This tool is not a part of the official tldraw project.

Due to the architecture of tldraw, export depends on functionality provided by a web browser. So, behind the scenes, this app serves a local instance of tldraw, then loads a .tldr and invokes the export download via the Puppeteer headless browser automation tool.

This can be a bit slow, (exporting seems to take a second or two), but in the context of a statically-generated content pipeline it's not the end of the world.

In terms of Puppeteer vs. Playwright and other headless browser automation tools, it looks like Puppeteer's performance likely compares favorably. (Though I have not tested and benchmarked the alternatives in the specific context of tldraw-cli.)

The local instance of tldraw includes its assets dependencies, so the tool should work correctly without internet access.

Track the tldraw changelog.

The future

Eventually, I think it would make sense for some kind of CLI tool like this one to be part of the core tldraw project. (Similar to how tldraw-vscode is currently integrated.)

I'm consciously releasing this tool under the @kitschpatrol namespace on NPM to leave the tldraw-cli package name available to the core tldraw project.

Maintainers

@kitschpatrol

Contributing

Issues and pull requests are welcome.

License

MIT © Eric Mika