@kitschpatrol/tldraw-cli 4.1.0 → 4.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/cli.js +2 -0
- package/package.json +2 -2
- package/readme.md +112 -59
package/bin/cli.js
CHANGED
|
@@ -23156,6 +23156,7 @@ await yargsInstance.scriptName("tldraw-cli").command("$0 <command>", "CLI tools
|
|
|
23156
23156
|
'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.',
|
|
23157
23157
|
(yargs) => yargs.positional("files-or-urls", {
|
|
23158
23158
|
array: true,
|
|
23159
|
+
default: void 0,
|
|
23159
23160
|
demandOption: true,
|
|
23160
23161
|
describe: "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`.",
|
|
23161
23162
|
type: "string"
|
|
@@ -23276,6 +23277,7 @@ await yargsInstance.scriptName("tldraw-cli").command("$0 <command>", "CLI tools
|
|
|
23276
23277
|
"Open a tldraw `.tldr` file or tldraw.com URL your default browser. Uses a locally-hosted instance of tldraw. Call `open` without an argument to open a blank sketch. Sketches opened via URL are 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.",
|
|
23277
23278
|
(yargs) => yargs.positional("files-or-urls", {
|
|
23278
23279
|
array: true,
|
|
23280
|
+
default: void 0,
|
|
23279
23281
|
describe: "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`.",
|
|
23280
23282
|
type: "string"
|
|
23281
23283
|
}).option("local", {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kitschpatrol/tldraw-cli",
|
|
3
|
-
"version": "4.1.
|
|
3
|
+
"version": "4.1.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "A tiny little CLI tool for exporting tldraw sketches to svg or png images.",
|
|
6
6
|
"repository": {
|
|
@@ -46,7 +46,7 @@
|
|
|
46
46
|
"puppeteer": "^22.2.0"
|
|
47
47
|
},
|
|
48
48
|
"devDependencies": {
|
|
49
|
-
"@kitschpatrol/shared-config": "^4.4.
|
|
49
|
+
"@kitschpatrol/shared-config": "^4.4.1",
|
|
50
50
|
"@sindresorhus/slugify": "^2.2.1",
|
|
51
51
|
"@tldraw/assets": "2.0.0-canary.e6e4e7f6cbac",
|
|
52
52
|
"@tldraw/tldraw": "2.0.0-canary.e6e4e7f6cbac",
|
package/readme.md
CHANGED
|
@@ -1,10 +1,36 @@
|
|
|
1
|
+
<!--+ Warning: Content in HTML comment blocks generated by mdat on 2024-02-22 +-->
|
|
2
|
+
|
|
3
|
+
<!-- header -->
|
|
4
|
+
|
|
1
5
|
# @kitschpatrol/tldraw-cli
|
|
2
6
|
|
|
3
|
-
[](https://npmjs.com/package/@kitschpatrol/tldraw-cli)
|
|
7
|
+
[](https://npmjs.com/package/@kitschpatrol/tldraw-cli)
|
|
8
|
+
[](https://opensource.org/licenses/MIT)
|
|
9
|
+
|
|
10
|
+
**A tiny little CLI tool for exporting tldraw sketches to svg or png images.**
|
|
11
|
+
|
|
12
|
+
<!-- /header -->
|
|
13
|
+
|
|
14
|
+
<!-- table-of-contents { maxDepth: 2 } -->
|
|
15
|
+
|
|
16
|
+
## Table of contents
|
|
17
|
+
|
|
18
|
+
- [Overview](#overview)
|
|
19
|
+
- [Installation](#installation)
|
|
20
|
+
- [Command line usage](#command-line-usage)
|
|
21
|
+
- [Examples](#examples)
|
|
22
|
+
- [API usage](#api-usage)
|
|
23
|
+
- [Background](#background)
|
|
24
|
+
- [Implementation notes](#implementation-notes)
|
|
25
|
+
- [The future](#the-future)
|
|
26
|
+
- [Contributing](#contributing)
|
|
27
|
+
- [License](#license)
|
|
28
|
+
|
|
29
|
+
<!-- /table-of-contents -->
|
|
4
30
|
|
|
5
31
|
## Overview
|
|
6
32
|
|
|
7
|
-
|
|
33
|
+
A CLI app to automate conversion and export of [tldraw](https://tldraw.dev) URLs and `.tldr` files into SVG or PNG image formats.
|
|
8
34
|
|
|
9
35
|
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.
|
|
10
36
|
|
|
@@ -32,70 +58,86 @@ npm install --global @kitschpatrol/tldraw-cli
|
|
|
32
58
|
|
|
33
59
|
## Command line usage
|
|
34
60
|
|
|
35
|
-
|
|
61
|
+
<!-- cli-help -->
|
|
36
62
|
|
|
37
|
-
`tldraw-cli`
|
|
63
|
+
#### Command: `tldraw-cli`
|
|
38
64
|
|
|
39
|
-
|
|
65
|
+
CLI tools for tldraw.
|
|
40
66
|
|
|
41
|
-
|
|
67
|
+
This section lists top-level commands for `tldraw-cli`.
|
|
68
|
+
|
|
69
|
+
Usage:
|
|
70
|
+
|
|
71
|
+
```txt
|
|
42
72
|
tldraw-cli <command>
|
|
43
73
|
```
|
|
44
74
|
|
|
45
|
-
|
|
75
|
+
| Command | Argument | Description |
|
|
76
|
+
| -------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
77
|
+
| `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. |
|
|
78
|
+
| `open` | `[files-or-urls..]` | Open a tldraw `.tldr` file or tldraw\.com URL your default browser. Uses a locally-hosted instance of tldraw. Call `open` without an argument to open a blank sketch. Sketches opened via URL are 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. |
|
|
46
79
|
|
|
47
|
-
|
|
|
48
|
-
|
|
|
49
|
-
| `
|
|
80
|
+
| Option | Alias | Description | Type |
|
|
81
|
+
| ----------- | ----- | ------------------- | --------- |
|
|
82
|
+
| `--help` | `-h` | Show help | `boolean` |
|
|
83
|
+
| `--version` | `-v` | Show version number | `boolean` |
|
|
50
84
|
|
|
51
|
-
|
|
52
|
-
| ----------- | ----- | -------------------- |
|
|
53
|
-
| `--help ` | `-h` | Show help. |
|
|
54
|
-
| `--version` | `-v` | Show version number. |
|
|
85
|
+
_See the sections below for more information on each subcommand._
|
|
55
86
|
|
|
56
|
-
####
|
|
87
|
+
#### Subcommand: `tldraw-cli export`
|
|
57
88
|
|
|
58
|
-
|
|
89
|
+
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.
|
|
90
|
+
|
|
91
|
+
Usage:
|
|
92
|
+
|
|
93
|
+
```txt
|
|
59
94
|
tldraw-cli export <files-or-urls..>
|
|
60
95
|
```
|
|
61
96
|
|
|
62
|
-
|
|
97
|
+
| Positional Argument | Description | Type |
|
|
98
|
+
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
|
|
99
|
+
| `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` |
|
|
63
100
|
|
|
64
|
-
|
|
|
65
|
-
|
|
|
66
|
-
|
|
|
101
|
+
| Option | Alias | Description | Type | Default |
|
|
102
|
+
| --------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------- |
|
|
103
|
+
| `--format` | `-f` | Output image format. | `string` | `"svg"` |
|
|
104
|
+
| `--output` | `-o` | Output image directory. | `string` | `"./"` |
|
|
105
|
+
| `--name` | `-n` | Output image name (without extension). | `string` | The original file name or URL id is used. |
|
|
106
|
+
| `--frames` | | Export each sketch "frame" as a separate image. Pass one or more frame names or IDs to export specific frames, or skip the arguments to export all frames. | `array` | `false` |
|
|
107
|
+
| `--transparent` | `-t` | Export an image with a transparent background. | `boolean` | `false` |
|
|
108
|
+
| `--dark` | `-d` | Export a dark theme version of the image. | `boolean` | `false` |
|
|
109
|
+
| `--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` |
|
|
110
|
+
| `--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` |
|
|
111
|
+
| `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to `stderr` for ease of redirection. | `boolean` | `false` |
|
|
112
|
+
| `--help` | `-h` | Show help | `boolean` | |
|
|
113
|
+
| `--version` | `-v` | Show version number | `boolean` | |
|
|
67
114
|
|
|
68
|
-
|
|
69
|
-
| ------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
|
|
70
|
-
| `--format [string]` | `-f` | Output image format, one of `svg`, `png`, `json`, or `tldr`. | `svg` |
|
|
71
|
-
| `--output <string>` | `-o` | Output image directory. | `./` |
|
|
72
|
-
| `--name <string>` | `-n` | Output image name (without extension). By default the original file name or URL id is used. | |
|
|
73
|
-
| `--frames [array]` | | Export each sketch "frame" as a separate image. Pass one or more frame names or IDs to export specific frames, or skip the arguments to export all frames. | `false` |
|
|
74
|
-
| `--transparent ` | `-t` | Export an image with a transparent background. | `false` |
|
|
75
|
-
| `--dark ` | `-d` | Export a dark theme version of the image. | `false` |
|
|
76
|
-
| `--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. | `false` |
|
|
77
|
-
| `--print` | `-p` | Print the exported image(s) to stdout instead of saving to a file. Incompatible with `--output`, and ignores `--name`. PNGs are printed as base64-encoded strings. | `false` |
|
|
78
|
-
| `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to `stderr` for ease of redirection. | `false` |
|
|
115
|
+
#### Subcommand: `tldraw-cli open`
|
|
79
116
|
|
|
80
|
-
|
|
117
|
+
Open a tldraw `.tldr` file or tldraw\.com URL your default browser. Uses a locally-hosted instance of tldraw. Call `open` without an argument to open a blank sketch. Sketches opened via URL are 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.
|
|
81
118
|
|
|
82
|
-
|
|
119
|
+
Usage:
|
|
120
|
+
|
|
121
|
+
```txt
|
|
83
122
|
tldraw-cli open [files-or-urls..]
|
|
84
123
|
```
|
|
85
124
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
125
|
+
| Positional Argument | Description | Type |
|
|
126
|
+
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
|
|
127
|
+
| `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`. _(Optional.)_ | `array` |
|
|
89
128
|
|
|
90
|
-
|
|
|
91
|
-
|
|
|
92
|
-
| `
|
|
129
|
+
| Option | Alias | Description | Type | Default |
|
|
130
|
+
| ----------- | ----- | ------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
|
|
131
|
+
| `--local` | `-l` | Open the file or URL in a local instance of tldraw, instead of tldraw\.com. | `boolean` | `false` |
|
|
132
|
+
| `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to `stderr` for ease of redirection. | `boolean` | `false` |
|
|
133
|
+
| `--help` | `-h` | Show help | `boolean` | |
|
|
134
|
+
| `--version` | `-v` | Show version number | `boolean` | |
|
|
93
135
|
|
|
94
|
-
|
|
136
|
+
<!-- /cli-help -->
|
|
95
137
|
|
|
96
|
-
|
|
138
|
+
### Examples
|
|
97
139
|
|
|
98
|
-
|
|
140
|
+
#### Basic `.tldr` file image export
|
|
99
141
|
|
|
100
142
|
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.
|
|
101
143
|
|
|
@@ -105,17 +147,17 @@ tldraw-cli export your-drawing.tldr
|
|
|
105
147
|
|
|
106
148
|
The file will retain its original name, e.g. `your-drawing.svg`
|
|
107
149
|
|
|
108
|
-
|
|
150
|
+
#### Basic tldraw\.com image download
|
|
109
151
|
|
|
110
152
|
```sh
|
|
111
153
|
tldraw-cli export https://www.tldraw.com/s/v2_c_JsxJk8dag6QsrqExukis4
|
|
112
154
|
```
|
|
113
155
|
|
|
114
|
-
The tldraw
|
|
156
|
+
The tldraw\.com URL's id (e.g. `v2_c_JsxJk8dag6QsrqExukis4`) will be used for the file name.
|
|
115
157
|
|
|
116
158
|
This is approximately equivalent to clicking the tldraw\.com "☰ → Edit → Export As → SVG" menu item.
|
|
117
159
|
|
|
118
|
-
|
|
160
|
+
#### Export a remote tldraw\.com image to a local .tldr file
|
|
119
161
|
|
|
120
162
|
```sh
|
|
121
163
|
tldraw-cli export https://www.tldraw.com/s/v2_c_JsxJk8dag6QsrqExukis4 --format tldr
|
|
@@ -125,7 +167,7 @@ This is approximately equivalent to clicking the tldraw\.com "☰ → File → S
|
|
|
125
167
|
|
|
126
168
|
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).
|
|
127
169
|
|
|
128
|
-
|
|
170
|
+
#### Export to a specific image / file format
|
|
129
171
|
|
|
130
172
|
```sh
|
|
131
173
|
tldraw-cli export your-drawing.tldr --format png
|
|
@@ -133,7 +175,7 @@ tldraw-cli export your-drawing.tldr --format png
|
|
|
133
175
|
|
|
134
176
|
This is approximately equivalent to clicking the tldraw\.com "☰ → Edit → Export As → PNG" menu item.
|
|
135
177
|
|
|
136
|
-
|
|
178
|
+
#### Export with a transparent background
|
|
137
179
|
|
|
138
180
|
```sh
|
|
139
181
|
tldraw-cli export your-drawing.tldr --transparent --format png
|
|
@@ -141,7 +183,7 @@ tldraw-cli export your-drawing.tldr --transparent --format png
|
|
|
141
183
|
|
|
142
184
|
This is approximately equivalent to checking the tldraw\.com "☰ → Edit → Export As → ☐ Transparent" menu item.
|
|
143
185
|
|
|
144
|
-
|
|
186
|
+
#### Export to a specific destination
|
|
145
187
|
|
|
146
188
|
```sh
|
|
147
189
|
tldraw-cli export your-drawing.tldr --output ~/Desktop
|
|
@@ -149,7 +191,7 @@ tldraw-cli export your-drawing.tldr --output ~/Desktop
|
|
|
149
191
|
|
|
150
192
|
Exports to `~/Desktop/your-drawing.svg`
|
|
151
193
|
|
|
152
|
-
|
|
194
|
+
#### Export to a specific destination and filename
|
|
153
195
|
|
|
154
196
|
```sh
|
|
155
197
|
tldraw-cli export your-drawing.tldr --output ~/Desktop --name not-your-drawing
|
|
@@ -157,7 +199,7 @@ tldraw-cli export your-drawing.tldr --output ~/Desktop --name not-your-drawing
|
|
|
157
199
|
|
|
158
200
|
Exports to `~/Desktop/not-your-drawing.svg`
|
|
159
201
|
|
|
160
|
-
|
|
202
|
+
#### Export all frames from a tldraw\.com URL
|
|
161
203
|
|
|
162
204
|
```sh
|
|
163
205
|
tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames
|
|
@@ -173,19 +215,19 @@ The frame name will be slugified.
|
|
|
173
215
|
|
|
174
216
|
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.
|
|
175
217
|
|
|
176
|
-
|
|
218
|
+
#### Export a specific frame from a tldraw\.com URL
|
|
177
219
|
|
|
178
220
|
```sh
|
|
179
221
|
tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames "Frame 3"
|
|
180
222
|
```
|
|
181
223
|
|
|
182
|
-
|
|
224
|
+
#### Export multiple frames from a tldraw\.com URL
|
|
183
225
|
|
|
184
226
|
```sh
|
|
185
227
|
tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames "Frame 1" "Frame 3"
|
|
186
228
|
```
|
|
187
229
|
|
|
188
|
-
|
|
230
|
+
#### Export to JSON
|
|
189
231
|
|
|
190
232
|
```sh
|
|
191
233
|
tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --format "json"
|
|
@@ -195,13 +237,13 @@ The `.tldr` file format is also JSON under the covers, but the `--format json` f
|
|
|
195
237
|
|
|
196
238
|
I'm not completely clear on the use-case for this format, but since tldr.com supports it, so too shall `tldraw-cli`.
|
|
197
239
|
|
|
198
|
-
|
|
240
|
+
#### Write an SVG to stdout
|
|
199
241
|
|
|
200
242
|
```sh
|
|
201
243
|
tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --print
|
|
202
244
|
```
|
|
203
245
|
|
|
204
|
-
|
|
246
|
+
#### Open a tldraw\.com URL
|
|
205
247
|
|
|
206
248
|
```sh
|
|
207
249
|
tldraw-cli open https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw
|
|
@@ -299,8 +341,8 @@ On GitHub:
|
|
|
299
341
|
|
|
300
342
|
On Discord:
|
|
301
343
|
|
|
302
|
-
- [@jorisjh in #
|
|
303
|
-
- [@Nitsuj in #
|
|
344
|
+
- [@jorisjh in #ideas\_old](https://discord.com/channels/859816885297741824/859816885801713730/1156880056501665802)
|
|
345
|
+
- [@Nitsuj in #ideas\_old](https://discord.com/channels/859816885297741824/859816885801713730/1020352607920869406)
|
|
304
346
|
|
|
305
347
|
## Implementation notes
|
|
306
348
|
|
|
@@ -316,14 +358,13 @@ The local instance of tldraw includes its assets dependencies, so the tool shoul
|
|
|
316
358
|
|
|
317
359
|
## The future
|
|
318
360
|
|
|
319
|
-
|
|
361
|
+
Current plans for future improvements include the following:
|
|
320
362
|
|
|
321
363
|
- Add save button to local tldraw
|
|
322
364
|
- Accept globs and optimize batch processing with a single Puppeteer instance
|
|
323
365
|
- Add CLI tests
|
|
324
366
|
- Implement the ability to export specific pages as separate image files
|
|
325
367
|
- Add an option flag to set dpi when exporting to a bitmap format
|
|
326
|
-
- Additional commands beyond sketch conversion / export?
|
|
327
368
|
- There's room for optimization in how tldraw functions are passed to Puppeteer
|
|
328
369
|
- There's room for optimization in the `--print` option implementation
|
|
329
370
|
|
|
@@ -332,3 +373,15 @@ Any other suggestions are welcome.
|
|
|
332
373
|
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](https://github.com/tldraw/tldraw/tree/main/apps/vscode) is currently integrated.)
|
|
333
374
|
|
|
334
375
|
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.
|
|
376
|
+
|
|
377
|
+
<!-- footer -->
|
|
378
|
+
|
|
379
|
+
## Contributing
|
|
380
|
+
|
|
381
|
+
[Issues](https://github.com/kitschpatrol/tldraw-cli/issues) and pull requests are welcome.
|
|
382
|
+
|
|
383
|
+
## License
|
|
384
|
+
|
|
385
|
+
[MIT](license.txt) © Eric Mika
|
|
386
|
+
|
|
387
|
+
<!-- /footer -->
|