@kitschpatrol/tldraw-cli 4.1.1 → 4.2.0

package/readme.md

@@ -1,4 +1,4 @@
-<!--+ Warning: Content in HTML comment blocks generated by mdat on 2024-02-22 +-->
+<!--+ Warning: Content inside HTML comment blocks was generated by mdat and may be overwritten. +-->
 
 <!-- header -->
 
@@ -7,7 +7,7 @@
 [![NPM Package @kitschpatrol/tldraw-cli](https://img.shields.io/npm/v/@kitschpatrol/tldraw-cli.svg)](https://npmjs.com/package/@kitschpatrol/tldraw-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**A tiny little CLI tool for exporting tldraw sketches to svg or png images.**
+**A CLI tool for exporting tldraw sketch URLs and local .tldr files to SVG or PNG images.**
 
 <!-- /header -->
 
@@ -17,12 +17,13 @@
 
 - [Overview](#overview)
 - [Installation](#installation)
-- [Command line usage](#command-line-usage)
-  - [Examples](#examples)
-- [API usage](#api-usage)
+- [Usage](#usage)
+  - [CLI](#cli)
+  - [API](#api)
 - [Background](#background)
 - [Implementation notes](#implementation-notes)
 - [The future](#the-future)
+- [Maintainers](#maintainers)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -30,7 +31,7 @@
 
 ## Overview
 
-A CLI app to automate conversion and export of [tldraw](https://tldraw.dev) URLs and `.tldr` files into SVG or PNG image formats.
+A CLI app to automate conversion and export of [tldraw](https://tldraw.dev) 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.
 
@@ -56,7 +57,9 @@ npm install --save-dev @kitschpatrol/tldraw-cli
 npm install --global @kitschpatrol/tldraw-cli
 ```
 
-## Command line usage
+## Usage
+
+### CLI
 
 <!-- cli-help -->
 
@@ -72,10 +75,10 @@ Usage:
 tldraw-cli <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 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. |
+| 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. |
 
 | Option      | Alias | Description         | Type      |
 | ----------- | ----- | ------------------- | --------- |
@@ -114,7 +117,7 @@ tldraw-cli export <files-or-urls..>
 
 #### Subcommand: `tldraw-cli open`
 
-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.
+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.
 
 Usage:
 
@@ -135,9 +138,9 @@ tldraw-cli open [files-or-urls..]
 
 <!-- /cli-help -->
 
-### Examples
+#### Examples
 
-#### Basic `.tldr` file image export
+##### 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.
 
@@ -147,7 +150,7 @@ tldraw-cli export your-drawing.tldr
 
 The file will retain its original name, e.g. `your-drawing.svg`
 
-#### Basic tldraw\.com image download
+##### Basic tldraw\.com image download
 
 ```sh
 tldraw-cli export https://www.tldraw.com/s/v2_c_JsxJk8dag6QsrqExukis4
@@ -157,7 +160,7 @@ The tldraw\.com URL's id (e.g. `v2_c_JsxJk8dag6QsrqExukis4`) will be used for th
 
 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
+##### Export a remote tldraw\.com image to a local .tldr file
 
 ```sh
 tldraw-cli export https://www.tldraw.com/s/v2_c_JsxJk8dag6QsrqExukis4 --format tldr
@@ -167,7 +170,7 @@ This is approximately equivalent to clicking the tldraw\.com "☰ → File → S
 
 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
+##### Export to a specific image / file format
 
 ```sh
 tldraw-cli export your-drawing.tldr --format png
@@ -175,7 +178,7 @@ tldraw-cli 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
+##### Export with a transparent background
 
 ```sh
 tldraw-cli export your-drawing.tldr --transparent --format png
@@ -183,7 +186,7 @@ tldraw-cli 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
+##### Export to a specific destination
 
 ```sh
 tldraw-cli export your-drawing.tldr --output ~/Desktop
@@ -191,7 +194,7 @@ tldraw-cli export your-drawing.tldr --output ~/Desktop
 
 Exports to `~/Desktop/your-drawing.svg`
 
-#### Export to a specific destination and filename
+##### Export to a specific destination and filename
 
 ```sh
 tldraw-cli export your-drawing.tldr --output ~/Desktop --name not-your-drawing
@@ -199,7 +202,7 @@ tldraw-cli 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
+##### Export all frames from a tldraw\.com URL
 
 ```sh
 tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames
@@ -215,19 +218,19 @@ 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
+##### Export a specific frame from a tldraw\.com URL
 
 ```sh
 tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames "Frame 3"
 ```
 
-#### Export multiple frames from a tldraw\.com URL
+##### Export multiple frames from a tldraw\.com URL
 
 ```sh
 tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames "Frame 1" "Frame 3"
 ```
 
-#### Export to JSON
+##### Export to JSON
 
 ```sh
 tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --format "json"
@@ -237,13 +240,13 @@ The `.tldr` file format is also JSON under the covers, but the `--format json` f
 
 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
+##### Write an SVG to stdout
 
 ```sh
 tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --print
 ```
 
-#### Open a tldraw\.com URL
+##### Open a tldraw\.com URL
 
 ```sh
 tldraw-cli open https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw
@@ -251,7 +254,7 @@ tldraw-cli 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 usage
+### API
 
 The `export` command's functionality is also provided in module form for use in TypeScript or JavaScript Node projects.
 
@@ -356,6 +359,8 @@ In terms of Puppeteer vs. Playwright and other headless browser automation tools
 
 The local instance of tldraw includes its assets dependencies, so the tool should work correctly without internet access.
 
+Track the [tldraw changelog](https://github.com/tldraw/tldraw/blob/main/CHANGELOG.md).
+
 ## The future
 
 Current plans for future improvements include the following:
@@ -374,6 +379,10 @@ Eventually, I think it would make sense for some kind of CLI tool like this one
 
 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](https://github.com/kitschpatrol)
+
 <!-- footer -->
 
 ## Contributing