FacetDocs

Commands

Every command, with its arguments. Each runs against a file with facet --doc FILE COMMAND (add --headless for a host of your own, without the app), or against the open window without --doc. facet guide TOOL prints the same for one command.

The table names each argument as facet call TOOL '{json}' takes it; the flag beside it is the command-line form.

build

Create a whole tree in one call: frames with auto layout, text, images, vectors, instances with variants and overrides, component sets and variable references. Returns every node id by layer name. From a generator: facet build --watch --run 'python3 make.py' [--files 'recipes/*.py'] runs it, syncs the JSON it prints (or the @file it writes) and does both again whenever a watched file changes: without --files, the source files under the current folder (the generator among them); with --files, only the files those patterns match, so name the generator's own file too. As lines: facet build --stream reads one layer per line (kind#Name key=value | text, two spaces of indentation to go inside the line above; then PATCH NAME key=value, REPLACE NAME | text, INSERT kind#Name after=SIBLING, DELETE NAME) from stdin or @file.sxl and syncs what each batch of lines changed, so a design shows while it is still being written; --print writes the JSON the lines stand for.

facet build @screen.json [--sync] [--replace] [--again] [--strict] [--parent NODE [--index N | --before SIBLING]] [--component] [--preview out.png]
ArgumentFlagTypeAbout
schemaNODErequiredthe tree to build (see the grammar below); a bare node also works
parentId--parentid / namebuild inside this frame instead of on the page
index--indexnumberwith parentId: where the new layer goes among the parent's children, 0 first (default: last)
before--beforeid / namewith parentId: the child of the parent the new layer goes before
position{x, y}page position of the root (default: right of existing content)
convertToComponent--componentboolmake the root a main component
replace--replaceboolreplace the top-level node of the same name: the new one takes its place, its instances move to the new components with the same names (else the variants keeping their values), and the old one is deleted (one undo step)
again--againbooladd a second top-level layer of a name that is already there; without it (and without sync or replace) such a build is refused, since it is nearly always a build run again where a sync was meant
sync--syncboolchange the top-level node of the same name in place to match: layers that still match keep their ids, instances and comments; the rest are added or deleted; gap, padding, fill, stroke, cornerRadius, opacity, effects, rotation and a text's width and maxLines an earlier source wrote and this one leaves out go back to their defaults (one undo step)
presenceboolwhether the app shows this call: its agent cursor and the outlines of what it changed. Left out, a sync that repeats the same agent's sync of the same layers within a few seconds (a replay) shows neither and other calls show both; false hides them (CLI --quiet), true shows them
pruneboolwith sync: delete the page's top-level layers this call does not write (main components, component sets and the Icons frame stay), so a source that writes fewer frames than before leaves none behind; the reply names them (SYNC_PRUNED)
preview--previewpathwrite a PNG of the result (the written node, or the page)
facet build '{"name": "Card", "width": 320, "padding": 16, "gap": 8, "fill": "#FFFFFF", "cornerRadius": 12, "column": [{"text": "Hello", "font": "Inter 20 700"}, "Plain text"]}'

source

A layer written in the build language, shortest form first: what you would write to build it, ready to edit and send back with build --sync. Variable bindings print as their variables (@Collection/name), a layer's mode as "mode", and a pinned layer in a frame by its place ("at": "center"). It names the kit's colours, presets and parts; the kit itself is facet kit, and a new file needs it first ({"kit": …, "nodes": [source]}).

facet source NODE [--depth N] [--detach]
ArgumentFlagTypeAbout
nodeIdid / name / selectorrequiredthe layer
depth--depthnumberlevels of children to include (all by default)
detach--detachboolwrite instances as the layers they show, not by their component's name, so the source builds in another file that lacks the components (CLI --detach)
facet source Card

kit

The document's kit: its font, colors, type presets and parts, as you would write it.

facet kit

pages

The document's pages; "add" makes a page and shows it (with "show": false, keeps the page showing), "show" shows one, "rename", "move" and "delete" change them; pages are named by name or id. Every tool works on the page showing, or on the page its "page" argument names (name or id) without showing it. Ids in later commands are those of the page showing: pass --page NAME, or show the page first.

facet page [list | add NAME [--keep] | copy PAGE NAME | show PAGE | rename [PAGE] NAME | move PAGE N | delete PAGE]
ArgumentFlagTypeAbout
addnameadd a page with this name and show it
copy{page: name}a new page holding a copy of every top-level layer of the page named, each where it was; component sets and main components stay where they are and the copies' instances follow them (one undo step)
showname / id / falseshow this page; with "add", false keeps the page showing
renamename / {page: name}rename the page showing, or each page named (one undo step)
move{page: position}move each page to a position in the page order, 0 first (one undo step)
deletepage / [pages]delete pages with their layers; the last page stays (one undo step)
facet call pages '{"add": "Flows"}'

modify

Change an existing node with the same keys as build; edit named descendants with "$nodes", an instance's layers with "$override" and its variant with "$variant".

facet modify NODE @props.json [--preview out.png]
ArgumentFlagTypeAbout
nodeIdid / name / selectorrequiredthe node to change: its id, or a layer name or selector that matches exactly one node (a name a top-level layer shares with layers inside others means the top-level one)
schemapropsrequiredkeys to set, e.g. {"fill": "#000", "$nodes": {"Title": {"text": "Hi"}}}
allboolchange every layer nodeId matches (a name several layers share, a selector, "A, B"), in one undo step
preview--previewpathwrite a PNG of the result (the written node, or the page)
facet modify 12 '{"$nodes":{"Title":{"text":"Welcome back"}},"fill":"#F8FAFC"}'

tree

The page structure: ids, names, types, positions and sizes, nested.

facet tree [NODE] [--depth N|all] [--full]
ArgumentFlagTypeAbout
nodeIdidstart here instead of the page
depth--depthnumber / "all"levels to expand (default 4); a node cut off below that has "truncated": true and its childCount
detail--full"full"every node with all its properties, as inspect shows them
facet tree --depth 2

inspect

Everything about one node in grammar keys: position, size, sizing, layout, look, text, component facts, children.

facet inspect NODE
ArgumentFlagTypeAbout
nodeIdidrequiredthe node
facet inspect 12

where

Where a layer is in code: the components it is in, innermost first, each with the file that defines it and, for an instance, where it is used; and the layer as the innermost component's own layer. From the $source a generator wrote (facet react dom --components writes the app's files).

facet where NODE
ArgumentFlagTypeAbout
nodeIdidrequiredthe node
facet where 12

probe

Lays nodes out as build would, without keeping them: returns each node's size and place and, for texts, the lines they take, the line height and where each line starts in the content (to paginate or split text). A list, or a kit with nodes, answers one result per node, in the kit's styles. It builds on a scratch copy: the document and its undo history are never touched.

facet probe JSON
ArgumentFlagTypeAbout
schemanode / [nodes] / {kit, nodes}requiredwhat to measure, as build takes it
facet --doc f.facet probe @block.json

reveal

Brings a layer into view in the window showing the file: centered at the same zoom when it fits, else framed whole (--fit always frames it). It changes only the view, never the document, and does not bring the window forward.

facet reveal NODE [--fit]
ArgumentFlagTypeAbout
nodeIdid / name / selectorrequiredthe layer
fit--fitboolframe the layer whole even when it already fits
facet reveal "Pricing card" --fit

find

Nodes matching a selector: Name, "[name^=Card]", "[type=text]", "[component=Button]" (the instances of a component or a set), "[fill=#2563EB]" (layers of that colour; a text by the colour of its words; "[fill=@brand]": bound to that variable), "[fontSize>20]" (texts by size: =, >, >=, <, <=), "[font=Inter]" (texts in a family), "[cornerRadius=8]" (a layer's own numbers: cornerRadius, width, height, opacity, with the same comparisons), "#12", "Card Title" (descendant), "Card > Title" (child), "A, B". Names may contain spaces ("Card Coil > Photo"); [name="..."] matches one name exactly.

facet find SELECTOR [--in NODE]
ArgumentFlagTypeAbout
selectorstringrequiredwhat to match
scopeidsearch inside this node only
facet find '[type=text]' --in 12

components

Component sets (with their variant properties and values in order, first is the default) and main components.

facet components

variables

Create a variable collection with any number of modes, in the document's variables (saved with the file, shown in the Variables window); a value may be {"alias": "Collection/name"}. Reference variables in builds as "@Collection/name|fallback": fills, strokes, gradient stop colors and positions, radius, stroke width, size, gap, padding, opacity (percent), font size, letter spacing, text and visibility stay bound, and set_mode switches a subtree's mode.

facet call variables @tokens.json
ArgumentFlagTypeAbout
collectionNamestringrequirede.g. Theme
modes[string]e.g. ["Light", "Dark"] (default one mode)
variables[{name, type, value / values}]requiredtype: color, number, string, boolean; values: {Mode: value or {"alias": "Collection/name"}}
facet call variables '{"collectionName":"Theme","modes":["Light","Dark"],"variables":[{"name":"surface","type":"color","values":{"Light":"#FFFFFF","Dark":"#0F172A"}}]}'

set_mode

Show a subtree in another mode of a collection: every property bound to that collection's variables takes the mode's value.

facet call set_mode '{"nodeId":ID,"collectionName":C,"modeName":M}'
ArgumentFlagTypeAbout
nodeIdidrequiredsubtree root
collectionNamestringrequiredthe collection
modeNamestringrequiredthe mode
facet call set_mode '{"nodeId":"12","collectionName":"Theme","modeName":"Dark"}'

design_system

Variables with their modes, components, and the colors and text styles in use.

facet call design_system

package

Save the design and write it with what it needs into one folder (default: "<name> package" beside it): the .facet document, the project's DESIGN.md, the system it follows at that version, fonts.json naming every family, and a README. Never overwrites a folder.

facet --doc F call package '{"out":"/abs/folder"}'
ArgumentFlagTypeAbout
outstringthe package folder (absolute)

systems

Design systems in the library (~/.facet/systems): each one's name, version, and absolute paths to its tokens.json (DTCG), DESIGN.md (rules) and folder. They are plain files; read and edit them directly.

facet call systems

system

One system (default: the one this file's project follows, named in the header of the DESIGN.md beside it): version, file paths, rules, published versions.

facet call system '{"name":"Acme"}'
ArgumentFlagTypeAbout
namestringsystem name

system_create

Make a system from this file: its tokens as tokens.json, the project's DESIGN.md (or a starter) as the system's rules, version 1.0.0; the project then follows it.

facet call system_create '{"name":"Acme","description":"..."}'
ArgumentFlagTypeAbout
namestringrequiredsystem name
descriptionstringone line about it
facet call system_create '{"name":"Acme"}'

system_use

Bring a system's tokens into this file (collections, modes, aliases, text, paint and shadow styles; existing ones update) and make the project follow it. Run it again after editing the system's files to take the changes.

facet call system_use '{"name":"Acme","version":"1.2.0"}'
ArgumentFlagTypeAbout
namestringsystem (default: the one followed)
versionstringa published version (default: the files as they are)
facet call system_use '{"name":"Acme"}'

system_save

Write this file's tokens to its system's tokens.json (unpublished until system_publish).

facet call system_save
ArgumentFlagTypeAbout
namestringsystem (default: the one followed)

system_publish

Record the system's files as a new version (major, minor, patch or an explicit 1.2.0) under versions/; a project that follows it moves to that version.

facet call system_publish '{"bump":"minor"}'
ArgumentFlagTypeAbout
namestringsystem (default: the one followed)
bumpstringmajor, minor (default), patch or a version
facet call system_publish '{"bump":"patch"}'

lint

Check the page against the design rules in DESIGN.md beside the file (colors, radii and spacing from tokens, text styles, fonts): the rules file's path, its rules and every layer that breaks one (main components and instance overrides; what instances show unchanged is not reported twice). Run it after edits.

facet call lint

duplicate

Copy nodes; a copy sits right of its source, past any layer already there. Optional "name" and "mode": {collectionName, modeName} for a themed copy.

facet copy NODE [NODE…] [--name NAME] [--mode Dark]
ArgumentFlagTypeAbout
nodeIds[id]requirednodes to copy
name--namestringname of the copy
mode--mode{collectionName, modeName}show the copy in this mode
previewpathwrite a PNG of the result (the written node, or the page)
facet call duplicate '{"nodeIds":["12"],"name":"Login Dark","mode":{"collectionName":"Theme","modeName":"Dark"}}'

delete

Delete nodes and their children.

facet delete NODE [NODE…]
ArgumentFlagTypeAbout
nodeIds[id]requirednodes to delete
facet delete 14

detach

Turn instances into ordinary layers that keep what they showed (their overrides and names); instances nested inside stay instances. One undo step.

facet detach NODE [NODE…]
ArgumentFlagTypeAbout
nodeIds[id]requiredthe instances to detach
facet detach "Pro card"

componentize

Make an existing frame, row or column a component, where it is; its uses are then written by its name ({"Card": {}}).

facet component NODE
ArgumentFlagTypeAbout
nodeIdid / name / selectorrequiredthe frame to make a component
facet component Card

group

Put layers of one parent in one layer of their own, in place. In a row or column they go into a row or column with the same gap, which lays out, takes new layers and copies like any other; placed freely (on the page, in a stack) they become a group, which moves its layers as one.

facet group NODE NODE… [--name NAME]
ArgumentFlagTypeAbout
nodeIds[id]requiredthe layers to group
name--namestringthe group's name
facet group A B --name Pair

replace

Replace words in every text of the page showing (or under one layer): each text that holds OLD exactly, capitals included, gets NEW in its place, in one undo step. A text with styled runs, and one inside an instance (set through the instance's property), is left and counted, so nothing loses its styling.

facet replace OLD NEW [--in NODE]
ArgumentFlagTypeAbout
find--intextrequiredthe words to look for
withtextrequiredthe words to put in their place
scopeid / nameonly the texts under this layer
facet replace "Sign up" "Join"

arrange

Lay top-level layers out in rows without touching what is inside them: the layers named, in that order, or every top-level layer of the page in reading order. With columns, a row holds that many and each column is as wide as its widest layer; without, one row. Rows are as tall as their tallest layer, gap apart (80 by default; [across, down]). It starts at the layers' top-left corner, or at "at". One undo step.

facet arrange [NODE ...] [--columns N] [--gap G | ACROSS,DOWN] [--at X,Y]
ArgumentFlagTypeAbout
nodeIds[id]top-level layers, in the order to place them (default: all, in reading order)
columns--columnsnumberlayers per row (default: one row)
gap--gapnumber / [across, down]space between layers (default 80)
at--at[x, y]where the first layer's top-left corner goes (default: where the layers' corner is now)
facet arrange --columns 4 --gap 80,120

move

Move layers into another frame (or onto the page with "parentId": null) at a child index (default: last, on top). Layers keep their place on the canvas unless the new parent's auto layout places them; absolute layers stay absolute. With "toPage" they move to another page at the same place, keeping their ids, names and component links.

facet move NODE [NODE…] --into PARENT [--index N] | --to-page NAME
ArgumentFlagTypeAbout
nodeIds[id]requiredlayers to move, in order
parentIdid / nullthe new parent frame (default and null: the page)
index--indexnumberchild index in the new parent (0 is the bottom of the stack and the start of a flow)
toPage--to-pagename / idmove the layers (top-level or not) onto this page instead, one undo step; instances stay linked
withinboolkeep the parent it has: last among its children, or at index (0 first)
facet call move '{"nodeIds":["14"],"parentId":"12","index":0}'

script

Run JavaScript (the body of an async function) over the same tools, as ONE call: canvas.build({...}), canvas.find({selector}), canvas.call(TOOL, args) and plugin-style nodes (facet.currentPage.findOne(...), node.fills = [...], facet.createFrame()). If it throws, everything it did is rolled back; otherwise it is one undo step. --read-only always rolls back. No file, network or clock access; timers run instantly in order. facet guide script lists the API. Each script runs in its own process: if the engine crashes or runs past its limit, that call fails with the reason and nothing it did is kept; the app keeps running.

facet script @file.js [--read-only] [--input JSON] [--timeout-ms N]
ArgumentFlagTypeAbout
scriptstringrequiredthe code; return gives the result, await works
readOnly--read-onlyboolroll back every change at the end (inspections and measurements)
input--inputany JSONa value the script reads as canvas.input
timeoutMs--timeout-msnumbertime limit (default 30000, at most 120000)
facet script 'const card = facet.currentPage.findOne(n => n.name === "Card"); card.resize(320, card.height); return card.width;'

paint_styles

Create paint styles: each one solid color, bound to a color variable when given as "@Collection/name|#fallback". Apply with "$fillStyle" or "$strokeStyle". A name that exists is kept ("reused": true); "update": true gives it the new color instead.

facet call paint_styles '{"styles":[{"name":"Brand/Accent","fill":"@Brand/accent|#2563EB"}]}'
ArgumentFlagTypeAbout
styleslistrequired[{"name", "fill"}]
updateboolredefine styles that exist (layers using them update)
facet call paint_styles '{"styles":[{"name":"Brand/Accent","fill":"#2563EB"}]}'

effect_styles

Create effect styles from "effects" lists (drop-shadow, inner-shadow, blur, background-blur, as in build). Apply with "$effectStyle". A name that exists is kept; "update": true redefines it and every layer following it updates.

facet call effect_styles '{"styles":[{"name":"Elevation/Card","effects":[...]}]}'
ArgumentFlagTypeAbout
styleslistrequired[{"name", "effects"}]
updateboolredefine styles that exist (layers using them update)
facet call effect_styles '{"styles":[{"name":"Elevation/Card","effects":[{"type":"drop-shadow","y":4,"blur":12,"color":"#0000001A"}]}]}'

text_styles

Create text styles from text keys (fontFamily, fontWeight or fontStyle, fontSize, lineHeight, letterSpacing). Apply with "$textStyle". A name that exists is kept; "update": true redefines it and every text following it updates.

facet call text_styles '{"styles":[{"name":"Body/Strong","fontFamily":"Inter","fontWeight":600,"fontSize":14}]}'
ArgumentFlagTypeAbout
styleslistrequired[{"name", "fontFamily", "fontWeight", "fontSize", ...}]
updateboolredefine styles that exist (texts following them update)

photos

Search openly licensed photos (Wikimedia Commons, then Openverse): title, web-sized thumbnail URL, size, license, author and page. Place one with "$image": URL, or the best match directly with "$image": "photo:masala chai". Results and photos are cached.

facet call photos '{"query":"masala chai","limit":6}'
ArgumentFlagTypeAbout
querystringrequiredwhat the photo shows
limitnumberresults (default 6, at most 20)
sheetpathalso write a contact sheet PNG: the results' thumbnails in a numbered grid with their titles and sources, to choose by looking
facet call photos '{"query":"masala chai","limit":6,"sheet":"chai.png"}'

fonts

Every font family a document can name: those installed here and every Google Fonts family (styles, weights, italics, variable axes, subsets, license, whether it renders here now). Name any of them as fontFamily: one not installed is downloaded and cached before the write measures (FONT_INSTALLED); text in it shows a metric-close stand-in only while it loads. Runs without a host too.

facet fonts list|search QUERY|info FAMILY|used [--json]
ArgumentFlagTypeAbout
actionlist / search / info / useddefault: info with family, search with query, else list; used: the families the page showing uses, with their weights, how many texts each sets and whether this machine has each
missingboolused: only the families this machine lacks
querystringsearch: part of a family name
familystringinfo: the family
categorystringlist: sans-serif, serif, display, handwriting or monospace
installedboollist: only families that render here now
googleboollist: only Google Fonts families
limitnumberfamilies returned (list 200, search 20)
facet fonts search 'playfair' && facet fonts info 'Playfair Display'

refresh_images

Re-read and decode every image under a node (or the page) from the document: how many were refreshed, and which layers miss their image.

facet call refresh_images '{"nodeId":ID}'
ArgumentFlagTypeAbout
nodeIdidsubtree (default: the page)
facet call refresh_images '{"nodeId":"12"}'

project

Create a project (a folder beside the served document), or reuse the one with that name ("reused": true).

facet call project '{"name":"Checkout"}'
ArgumentFlagTypeAbout
namestringrequiredproject name

file

Create an empty document in a project (or reuse it); the reply gives its path. Work on it with facet --doc PATH.

facet call file '{"projectId":"Checkout","title":"Cart"}'
ArgumentFlagTypeAbout
projectIdstringrequiredproject name
titlestringrequiredfile name (without .facet)

projects

Projects beside the served document, with their files.

facet call projects

undo

Revert the latest write call as a whole (however many engine steps it took). If the document changed since, revert one step.

facet undo

redo

Replay the call undo reverted.

facet redo

audit

Layout findings: content a fixed frame clips or that shows past a frame's edge (LAYOUT_OVERFLOW) and content an edge-pinned bar covers (LAYOUT_OCCLUDED). Every write runs it on what it wrote.

facet audit [NODE]
ArgumentFlagTypeAbout
nodeIdidaudit this subtree (default: the page)
facet audit 12

shot

Render nodes (or the page) to PNG, text included. LOOK at it after every write. The PNG is transparent outside the layers (so is --preview's); --background '#FFFFFF' fills it.

facet shot [NODE...] -o out.png [--scale 2] [--padding 0] [--background #FFFFFF] [--region x,y,w,h] [--isolate] [--span] [--props JSON | --each @sets.json]
ArgumentFlagTypeAbout
nodeIds[id]layers to frame, each by name, selector or id (default: the page)
outputpathrequiredPNG file to write
scale--scalenumberpixels per unit (default 1)
padding--paddingnumbermargin in units (default 0)
background--backgroundcolorcolor under the content (default transparent)
region--region[number]render this world rectangle, [x, y, w, h] with w and h above 0 (CLI --region x,y,w,h), instead of the area the layers span; --scale applies, --padding does not (default: the layers or the page)
isolate--isolateboolonly the named layers and what they hold, without the layers beside or over them (default: everything in the frame, as the canvas shows it)
sheetboolseveral layers that don't touch are set side by side in a contact sheet, 24 units apart, in the order named (default); false (CLI --span) renders the whole area they span
props--propsobjectrender one instance with these properties without keeping them: {"Month": "FEB", "Day": "29"}
each--each[object]a PNG per set of the instance's properties, in one call, none kept; output names each with {Property} or {#}: tiles/{Month}-{Day}.png
facet shot Card -o card.png --scale 2; facet shot Tile --each @dates.json -o 'tiles/{Month}-{Day}.png'

spec

Handoff: what a node is, its structure, every string, colors, typography, spacing, radii, shadows, instances, images, bound variables and component states.

facet spec NODE
ArgumentFlagTypeAbout
nodeIdidrequiredthe node
facet spec 12

measure

Handoff: layout as data (redlines): sizes, sizing modes, padding, gaps, insets and the space between siblings. With a second layer: the distance between the two, across and down (negative where they overlap), and between their centers.

facet measure NODE [--depth N] | facet measure NODE OTHER
ArgumentFlagTypeAbout
nodeIdidrequiredthe node
depth--depthnumberlevels of children (default 1)
toidanother layer: reply with the distance between the two instead
facet measure 12 --depth 2

swiftui

Handoff: a layer as a SwiftUI view. Rows and columns are HStack and VStack with their spacing, padding and alignment; a frame without auto layout is a ZStack with each child at its place; fills (colours and linear gradients), strokes, corner radii, clipping, shadows (the radius is the deviation Facet draws the blur with, 0.42 of it), opacity and rotation are written as modifiers; texts carry their font, size, weight, tracking, case and colour. Icons, vectors and pictures are written as Image("name") and listed in assets, to export with assets export. notes says what SwiftUI cannot say the same way (a wrapping row, a radial fill, a shadow's spread, line height as line spacing).

facet swiftui NODE [--name ViewName] [-o View.swift]
ArgumentFlagTypeAbout
nodeIdid / namerequiredthe layer
name--namestringthe view's type name (default: the layer's name as a type name)
outputpathwhere to write the Swift file (default: the code is in the reply)
facet swiftui "Popover" -o Popover.swift

compare

Handoff: how far a picture of the built thing (an app's own screenshot of a state) is from a design frame. The frame is rendered as shot renders it (from the command line: as export draws it whenever the two pictures differ, so a frame and its own export are the same), on white (the picture's transparent parts go on the same ground), at the picture's scale (worked out from its width unless given), and compared pixel by pixel: the share of pixels differing by more than the tolerance in any channel, the mean difference, and the box of the largest differing patch in the frame's units. output writes the picture greyed with the differing pixels in magenta. With failOver, the call fails when more than that percentage differ, so a test stops an implementation drifting from its design.

facet compare FRAME built.png [--scale 2] [--tolerance 8] [--fail-over 1] [-o diff.png]
ArgumentFlagTypeAbout
nodeIdid / namerequiredthe design frame
imagepathrequireda PNG of the built thing
scale--scalenumberpixels per unit of the picture (default: its width over the frame's)
tolerance--tolerance0..255how far a channel may be off before a pixel differs (default 8)
failOver--fail-overpercentfail when more than this share of pixels differ
outputpathwhere to write the difference picture
backgroundcolorwhat the frame is rendered on (default white)
designpatha PNG of the frame to compare with in place of rendering it here: the frame's own export at this scale. The command line passes it by itself when the pictures differ, so a frame and its own export are 0% apart
facet compare "Popover" build/popover@2x.png --fail-over 1 -o diff.png

tokens

Handoff: variables, or (when there are none) the colors, spacing, radii, shadows and text styles in use, as CSS custom properties, a TypeScript module or JSON. With include metrics: also a metrics group with the layout values of each layer under the node, named by layer and property (popover-width, popover-padding-top, popover-radius, popover-shadow-blur, title-font-size, title-line-height), for a generator to write an app's metrics from.

facet tokens export --format css|ts|json|dtcg [--mode M] [--node ID] [--include metrics] [-o FILE]
ArgumentFlagTypeAbout
format--formatcss / ts / json / dtcgrequiredoutput format
mode--modestringone mode of each collection
nodeId--nodeidinfer from, and take metrics from, this subtree only
include--include"metrics"also export each layer's sizes, spacing, radii, type and shadows
facet tokens export --format css -o tokens.css

assets

Handoff: image files, vectors as SVG and the font families in use, with a manifest.json. With set: one file for each layer directly inside that frame, named after the layer (the Icons frame's lucide:monitor is monitor.svg): svg, or png at a scale on a clear ground, ready for an asset catalogue.

facet assets export [NODE] --out DIR | facet assets export --set FRAME [--format svg|png] [--size 15] [--scale 3] [--color current|drawn] --out DIR
ArgumentFlagTypeAbout
output--outdirrequiredfolder to write
nodeIdidexport from this subtree only
set--setid / namea frame: export each layer directly inside it as a file named after it
format--formatsvg / pngwith set: the file format (default svg)
size--sizenumberwith set: the width each file is drawn for, in points, whatever size the layer has (15 for a 15 pt icon)
scale--scalenumberwith set and png: pixels per point (3 for @3x)
color--colorcurrent / drawnwith set and svg: "current" (default) writes an icon of one colour in currentColor, so it takes the colour of the text around it; "drawn" keeps the colours in the design
facet assets export 12 --out assets/

guide

This page. Topics: tools, grammar, results, or a tool name.

facet guide [TOPIC]
ArgumentFlagTypeAbout
topicstringtools, grammar, results or a tool name
facet guide build

Everything else

Files, hosts, the app window and behavior charts, as facet --help prints them:

facet: design by command, and drive the visible app

Agents: read `facet guide` first: it opens with a first screen in five steps (write JSON, build
--preview, look, shot), then every tool, the grammar and the result codes.
`facet --version` names this build.

  facet --doc FILE build @screen.json [--preview s.png]   one call builds a whole tree
  facet --doc FILE build --watch --run 'python3 make.py'  run a generator again when its files change, and sync
  facet --doc FILE build --watch --stop                   end that watch from another shell
  facet --doc FILE build --stream [@design.sxl | -]        a design written as lines, built while it is written
  facet --doc FILE react render screen.tsx [--watch]      a design written in React, built in place
  facet --doc FILE modify NODE @props.json [--all]        change a node (and named layers); --all: every layer NODE matches
  facet --doc FILE delete NODE [NODE…]                    remove layers (ids, names or selectors)
  facet --doc FILE rename NODE NAME                       name a layer
  facet --doc FILE move NODE… --into PARENT [--index N]   put layers inside another (or --to-page NAME; --end / --start: among its own parent's children)
  facet --doc FILE copy NODE… [--name NAME] [--mode Dark] copy layers, right of their source
  facet --doc FILE detach NODE… | group NODE NODE… [--name NAME]   an instance as ordinary layers; layers in one layer of their own
  facet --doc FILE component NODE                         make a frame a component, where it is
  facet --doc FILE page add NAME [--keep]                 add a page (--keep: without showing it); also page
                                                          show NAME, rename [OLD] NEW, move NAME N, delete NAME, list
  facet --doc FILE tree | inspect NODE | find SELECTOR | components | audit [NODE]
  facet --doc FILE where NODE                             the components a layer is in and their files
  facet --doc FILE spec NODE | measure NODE | shot [NODE] -o x.png
  facet --doc FILE arrange [NODE ...] [--columns N] [--gap G]   top-level frames into rows, contents untouched
  facet --doc FILE compare FRAME built.png [--fail-over 1] [-o diff.png]   an app's screenshot against its design
  facet --doc FILE swiftui NODE [--name ViewName] [-o View.swift]         a layer as a SwiftUI view
  facet --doc FILE tokens export --format css|ts|json|dtcg | assets export [NODE] --out DIR
  facet --doc FILE undo | redo                            whole calls
  facet --doc FILE call lint                              layers breaking the rules in DESIGN.md beside FILE
  facet --doc FILE call package ['{"out":DIR}']         FILE with its DESIGN.md, system and fonts in one folder
  facet [--doc FILE] call systems | system | system_create | system_use | system_save | system_publish
                                                           design systems: plain files in ~/.facet/systems/NAME
                                                           (tokens.json as DTCG, DESIGN.md); see `facet guide`
  facet [--doc FILE] history [list|version NAME|restore REF|diff FROM [TO]]   operation log and versions (also `version save NAME`)
  facet --doc FILE chart import @chart.json | chart FEATURE [--explore] | chart bind|design FEATURE @f.json
  facet --doc FILE states COMPONENT | states apply NODE VIEW | plays list|run | replay FEATURE PLAY --at MS
  facet --doc FILE act | act NODE EVENT                   what each instance's statechart takes now; send one event
  facet --doc FILE lattice FEATURE matrix|flow|designs|replay [--scenario k=v]
  facet --doc FILE shot NODE --state VIEW [--scenario k=v] [--design k=v] -o x.png
  facet --doc FILE call TOOL '{json}'                     any tool (variables, set_mode, duplicate, delete, ...)
  facet --doc FILE script @file.js [--read-only]          JavaScript over the tools as one call (facet guide script)
  facet close --doc FILE                                  save and stop the document's host
  facet --doc FILE --headless COMMAND                     own headless host even when the app has FILE open
  facet --doc FILE --page NAME COMMAND                    work on another page without showing it
  facet serve FILE [--socket PATH] [--font FILE]          run a headless host in the foreground
  facet [--doc FILE] mcp                                  the tools as an MCP server on stdio (facet mcp --help)

Set up (AI apps, Terminal, the skill; facet setup --help):
  facet setup [--json]                      each AI app (installed, connected), facet on PATH, the skill links
  facet setup connect CLIENT|all|skills     add Facet to Claude, Claude Code, Codex, Cursor or VS Code
  facet setup disconnect CLIENT|all|skills  remove only what Facet added (backups beside each changed file)
  facet setup cli [--user] | repair         facet on PATH; point everything at this copy after a move
  facet setup channel [beta|stable]         receive beta builds too, or stable releases only (the default)
  facet uninstall [--keep-data] [--yes] [--dry-run]  remove what Facet added, its data and the app; never your designs

Open files (registry ~/.facet/docs, app socket ~/.facet/app.sock; --doc FILE uses the app's host when the app has FILE open):
  facet files [--json] [--no-ping] [--front]   every open file: path, kind app|headless, pid, build, socket, lock holder, ping health (ms), the front tab; --front prints its path only
  facet app restart [--bundle PATH]  save every file, restart the app on the new build (default: its own bundle), reopen
                                      every tab and headless host on the same sockets with the same view; prints both builds
  facet open FILE [--socket PATH] [--focus] [--new-window | --no-window]
                                               open FILE in the running app (a tab in the current window, own socket; --new-window: own window, closed with the file; --no-window: headless host), or start the app
  facet focus FILE             select FILE's tab and bring its app window to the front
  facet close FILE [--no-save] close FILE's app window (saves unless --no-save) or stop its headless host

Without --doc (or CANVAS_DOC) commands drive the running app over its control socket:
  facet capabilities [--json] | schema [OP] | demo list|open CASE|step|reset|close
  facet tour [CASE] [--delay-ms N] | whats-new [--grep TEXT] [--since VERSION] [--titles] [--json] | try [FEATURE] [--json]
  facet inspect | select ID | drag HANDLE DX DY | zoom FACTOR | pan DX DY
  facet duplicate | undo | redo | fit | save | reopen
  facet front                  bring the window to the front (no other command does)
  facet send '{"op":"mask","enabled":true,"mode":"outline"}'
  facet export --out DIR [--frames] [--settings JSON] [--wait]   background job; export status|cancel [JOB]
  facet export --pdf OUT.pdf [--page PAGE] [--paper a4|letter|WxH] [--dpi N] [--text text|outlines] [--wait]   every top-level frame, a page each
  facet variables [list] [--type color] [--json] | variables rename OLD NEW | variables set NAME VALUE [--mode MODE] | tokens [--mode NAME] [-o OUT.json] | tokens import FILE.json [--json]
  facet renderer exact|tiles   draw every frame exactly, or compose in tiles

Without any host:
  facet render DOC -o OUT.png [--view content|saved] [--node ID] [--zoom Z] [--scale S] [--padding P] [--background #RRGGBB[AA]]
  facet export DOC --out DIR [--page P] [--node ID]... [--frames] [--format png|jpg|svg|pdf] [--size 2x|512w|512h] [--suffix S] [--text outlines|text]
  facet export DOC --pdf OUT.pdf [--page P] [--paper a4|letter|WxH] [--dpi N] [--text text|outlines]   frames fitted to paper; selectable text
  facet pdf IN.md [-o OUT.pdf] [--style STYLE.mdstyle.json] [--stats]   Markdown as paginated PDF pages
  facet tokens DOC [--mode NAME] [-o OUT.json]
  facet chart CHART.json|DIR [--explore] [--json]       a chart file's report (scr-kit interchange)
  facet guide [TOPIC] [--json]
  facet fonts list|search QUERY|info FAMILY|fetch FAMILY...|refresh [--json]   installed and Google Fonts families

Developer commands (measuring and debugging Facet itself) are under `facet dev --help`.

Global: --doc FILE, --socket PATH, --headless, --json; every command takes --help. Agent results print on stdout,
then `facet: warning:` and `facet: note:` lines on stderr, a write's closed by their count. Exit 0 = completed, 2 = invalid input or
unavailable, 3 = failed or unknown outcome (nothing changed for agent tools). No automatic retries.
Coordinates for drag, pan and pointer commands are canvas-local logical screen pixels; drag handles:
south_east, east, north_west, north, north_east, south, south_west, west, rotate.

Documentation for Facet 0.3.228-g032727de