8c72b62da0
* feat(cli): export Storybook stories beside many documents Accept several documents, or a quoted glob such as 'src/**/*.pen', and add --beside to write each document's stories, design images, and manifest into the document's own folder, next to the component's code. Documents export one after another, since documents in one folder share its manifest; a failed document is reported and the rest still export. --watch covers every matched document through one queue. Several documents need --beside or --output, and --page takes a single document. Refs #727 * fix(cli): resolve Storybook export documents by existence, not glob syntax Deciding between a path and a pattern by looking for glob characters missed extglobs, so 'src/+(a|b).pen' was opened as a literal filename, and it flagged an escaped star, so a file genuinely named that way went to the matcher. The character list also could not agree with Node's matcher: is-glob rejects a bare '?', picomatch accepts a parenthesised directory name. An existing path is now that file, and everything else goes to glob(), which matches a plain path to itself and expands every pattern it supports. --------- Co-authored-by: Danila Poyarkov <dev@dannote.net>
219 lines
6 KiB
Markdown
219 lines
6 KiB
Markdown
---
|
||
title: CLI Reference
|
||
description: Complete reference for all openpencil commands, options, and flags.
|
||
---
|
||
|
||
# CLI Reference
|
||
|
||
All commands accept a `.fig` file as a positional argument. When omitted, the CLI connects to the running desktop app via RPC.
|
||
|
||
## info
|
||
|
||
Show document info — pages, node counts, fonts, file size.
|
||
|
||
```sh
|
||
openpencil info [file] [--json]
|
||
```
|
||
|
||
| Option | Description |
|
||
|--------|-------------|
|
||
| `--json` | Output as JSON |
|
||
|
||
## tree
|
||
|
||
Print the node hierarchy.
|
||
|
||
```sh
|
||
openpencil tree [file] [options]
|
||
```
|
||
|
||
| Option | Description |
|
||
|--------|-------------|
|
||
| `--page` | Page name (default: first page) |
|
||
| `--depth` | Max depth (default: unlimited) |
|
||
| `--json` | Output as JSON |
|
||
|
||
## find
|
||
|
||
Search nodes by name or type.
|
||
|
||
```sh
|
||
openpencil find [file] [options]
|
||
```
|
||
|
||
| Option | Description |
|
||
|--------|-------------|
|
||
| `--name` | Node name (partial match, case-insensitive) |
|
||
| `--type` | Node type: `FRAME`, `TEXT`, `RECTANGLE`, `INSTANCE`, etc. |
|
||
| `--page` | Page name (default: all pages) |
|
||
| `--limit` | Max results (default: 100) |
|
||
| `--json` | Output as JSON |
|
||
|
||
## node
|
||
|
||
Show detailed properties of a node.
|
||
|
||
```sh
|
||
openpencil node [file] --id <id> [--json]
|
||
```
|
||
|
||
| Option | Description |
|
||
|--------|-------------|
|
||
| `--id` | **Required.** Node ID (e.g. `1:23`) |
|
||
| `--json` | Output as JSON |
|
||
|
||
## pages
|
||
|
||
List all pages in the document.
|
||
|
||
```sh
|
||
openpencil pages [file] [--json]
|
||
```
|
||
|
||
| Option | Description |
|
||
|--------|-------------|
|
||
| `--json` | Output as JSON |
|
||
|
||
## variables
|
||
|
||
List design variables and collections.
|
||
|
||
```sh
|
||
openpencil variables [file] [options]
|
||
```
|
||
|
||
| Option | Description |
|
||
|--------|-------------|
|
||
| `--collection` | Filter by collection name |
|
||
| `--type` | Filter by type: `COLOR`, `FLOAT`, `STRING`, `BOOLEAN` |
|
||
| `--json` | Output as JSON |
|
||
|
||
## export
|
||
|
||
Export to PNG, JPG, WEBP, SVG, JSX, HTML, `.fig`, or Storybook stories.
|
||
|
||
```sh
|
||
openpencil export [file] [options]
|
||
```
|
||
|
||
| Option | Alias | Description |
|
||
|--------|-------|-------------|
|
||
| `--format` | `-f` | `png` (default), `jpg`, `webp`, `svg`, `pdf`, `pptx`, `jsx`, `tailwind-jsx`, `html`, `fig`, `storybook` |
|
||
| `--output` | `-o` | Output file path (default: `<name>.<format>`); a directory for `storybook` (default: `<name>-stories`) |
|
||
| `--scale` | `-s` | Export scale (default: 1) |
|
||
| `--quality` | `-q` | Quality 0–100, JPG/WEBP only (default: 90) |
|
||
| `--page` | | Page name (default: first page; `fig`, `pptx`, and `storybook` default to every page) |
|
||
| `--node` | | Node ID to export (default: all top-level nodes) |
|
||
| `--style` | | JSX style: `openpencil` (default), `tailwind` (same as `-f tailwind-jsx`) |
|
||
| `--html` | | HTML mode: `fragment` (default), `standalone` |
|
||
| `--css` | | HTML CSS output: `inline` (default), `tailwind` |
|
||
| `--assets` | | Standalone HTML assets: `inline` (default), `external` |
|
||
| `--fonts` | | Standalone HTML font output: `assets`, `none` (default) |
|
||
| `--framework` | | Storybook framework: `react` (default), `vue`, `html` |
|
||
| `--design-images` | | Storybook: render a PNG per variant for the Design panel (default: on; `--no-design-images` to skip) |
|
||
| `--watch` | | Storybook: re-export whenever the document is saved |
|
||
| `--beside` | | Storybook: write each document's stories into the document's own folder; the file argument can then be several files or a quoted glob |
|
||
| `--thumbnail` | | Export page thumbnail instead of full render |
|
||
| `--width` | | Thumbnail width (default: 1920) |
|
||
| `--height` | | Thumbnail height (default: 1080) |
|
||
|
||
## import
|
||
|
||
Import HTML/CSS/Tailwind into an editable OpenPencil document.
|
||
|
||
```sh
|
||
openpencil import page.html [options]
|
||
```
|
||
|
||
| Option | Alias | Description |
|
||
|--------|-------|-------------|
|
||
| `--format` | `-f` | Output format: `fig` (default), `json` |
|
||
| `--output` | `-o` | Output file path (default: `<name>.<format>`) |
|
||
| `--css` | | CSS file to apply before conversion |
|
||
| `--css-text` | | Inline CSS text to apply before conversion |
|
||
| `--tailwind` | | Tailwind utility candidates to compile and apply |
|
||
| `--tailwind-file` | | File containing Tailwind utility candidates |
|
||
| `--page-name` | | Scene graph page name (default: `DOM/CSS`) |
|
||
| `--json` | | Print a machine-readable summary |
|
||
|
||
Examples:
|
||
|
||
```sh
|
||
openpencil import card.html --css card.css -o card.fig
|
||
openpencil import card.html --tailwind "flex flex-col gap-3 w-80 p-6 rounded-xl bg-white" -o card.fig
|
||
```
|
||
|
||
## eval
|
||
|
||
Execute JavaScript with the Figma Plugin API.
|
||
|
||
```sh
|
||
openpencil eval [file] [options]
|
||
```
|
||
|
||
| Option | Alias | Description |
|
||
|--------|-------|-------------|
|
||
| `--code` | `-c` | JavaScript code to execute |
|
||
| `--stdin` | | Read code from stdin |
|
||
| `--write` | `-w` | Write changes back to the input file |
|
||
| `--output` | `-o` | Write to a different file |
|
||
| `--json` | | Output as JSON |
|
||
| `--quiet` | `-q` | Suppress output |
|
||
|
||
## analyze colors
|
||
|
||
Analyze color palette usage across the document.
|
||
|
||
```sh
|
||
openpencil analyze colors [file] [options]
|
||
```
|
||
|
||
| Option | Description |
|
||
|--------|-------------|
|
||
| `--limit` | Max colors to show (default: 30) |
|
||
| `--threshold` | Distance threshold for clustering similar colors, 0–50 (default: 15) |
|
||
| `--similar` | Show similar color clusters |
|
||
| `--json` | Output as JSON |
|
||
|
||
## analyze typography
|
||
|
||
Analyze font family, size, and weight distribution.
|
||
|
||
```sh
|
||
openpencil analyze typography [file] [options]
|
||
```
|
||
|
||
| Option | Description |
|
||
|--------|-------------|
|
||
| `--group-by` | Group by: `family`, `size`, `weight` (default: show all styles) |
|
||
| `--limit` | Max styles to show (default: 30) |
|
||
| `--json` | Output as JSON |
|
||
|
||
## analyze spacing
|
||
|
||
Analyze gap and padding values across auto-layout frames.
|
||
|
||
```sh
|
||
openpencil analyze spacing [file] [options]
|
||
```
|
||
|
||
| Option | Description |
|
||
|--------|-------------|
|
||
| `--grid` | Base grid size to check against (default: 8) |
|
||
| `--json` | Output as JSON |
|
||
|
||
## analyze clusters
|
||
|
||
Find repeated node patterns — potential components.
|
||
|
||
```sh
|
||
openpencil analyze clusters [file] [options]
|
||
```
|
||
|
||
| Option | Description |
|
||
|--------|-------------|
|
||
| `--limit` | Max clusters to show (default: 20) |
|
||
| `--min-size` | Min node size in px (default: 30) |
|
||
| `--min-count` | Min instances to form a cluster (default: 2) |
|
||
| `--json` | Output as JSON |
|