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]
| Argument | Flag | Type | About | |
|---|---|---|---|---|
schema | NODE | required | the tree to build (see the grammar below); a bare node also works | |
parentId | --parent | id / name | build inside this frame instead of on the page | |
index | --index | number | with parentId: where the new layer goes among the parent's children, 0 first (default: last) | |
before | --before | id / name | with 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 | --component | bool | make the root a main component | |
replace | --replace | bool | replace 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 | --again | bool | add 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 | --sync | bool | change 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) | |
presence | bool | whether 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 | ||
prune | bool | with 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 | --preview | path | write 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]
| Argument | Flag | Type | About | |
|---|---|---|---|---|
nodeId | id / name / selector | required | the layer | |
depth | --depth | number | levels of children to include (all by default) | |
detach | --detach | bool | write 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]
| Argument | Flag | Type | About | |
|---|---|---|---|---|
add | name | add 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) | ||
show | name / id / false | show this page; with "add", false keeps the page showing | ||
rename | name / {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) | ||
delete | page / [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]
| Argument | Flag | Type | About | |
|---|---|---|---|---|
nodeId | id / name / selector | required | the 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) | |
schema | props | required | keys to set, e.g. {"fill": "#000", "$nodes": {"Title": {"text": "Hi"}}} | |
all | bool | change every layer nodeId matches (a name several layers share, a selector, "A, B"), in one undo step | ||
preview | --preview | path | write 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]
| Argument | Flag | Type | About | |
|---|---|---|---|---|
nodeId | id | start here instead of the page | ||
depth | --depth | number / "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
| Argument | Flag | Type | About | |
|---|---|---|---|---|
nodeId | id | required | the 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
| Argument | Flag | Type | About | |
|---|---|---|---|---|
nodeId | id | required | the 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
| Argument | Flag | Type | About | |
|---|---|---|---|---|
schema | node / [nodes] / {kit, nodes} | required | what 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]
| Argument | Flag | Type | About | |
|---|---|---|---|---|
nodeId | id / name / selector | required | the layer | |
fit | --fit | bool | frame 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]
| Argument | Flag | Type | About | |
|---|---|---|---|---|
selector | string | required | what to match | |
scope | id | search 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
| Argument | Flag | Type | About | |
|---|---|---|---|---|
collectionName | string | required | e.g. Theme | |
modes | [string] | e.g. ["Light", "Dark"] (default one mode) | ||
variables | [{name, type, value / values}] | required | type: 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}'
| Argument | Flag | Type | About | |
|---|---|---|---|---|
nodeId | id | required | subtree root | |
collectionName | string | required | the collection | |
modeName | string | required | the 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"}'
| Argument | Flag | Type | About | |
|---|---|---|---|---|
out | string | the 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"}'
| Argument | Flag | Type | About | |
|---|---|---|---|---|
name | string | system 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":"..."}'
| Argument | Flag | Type | About | |
|---|---|---|---|---|
name | string | required | system name | |
description | string | one 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"}'
| Argument | Flag | Type | About | |
|---|---|---|---|---|
name | string | system (default: the one followed) | ||
version | string | a 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
| Argument | Flag | Type | About | |
|---|---|---|---|---|
name | string | system (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"}'
| Argument | Flag | Type | About | |
|---|---|---|---|---|
name | string | system (default: the one followed) | ||
bump | string | major, 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]
| Argument | Flag | Type | About | |
|---|---|---|---|---|
nodeIds | [id] | required | nodes to copy | |
name | --name | string | name of the copy | |
mode | --mode | {collectionName, modeName} | show the copy in this mode | |
preview | path | write 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…]
| Argument | Flag | Type | About | |
|---|---|---|---|---|
nodeIds | [id] | required | nodes 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…]
| Argument | Flag | Type | About | |
|---|---|---|---|---|
nodeIds | [id] | required | the 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
| Argument | Flag | Type | About | |
|---|---|---|---|---|
nodeId | id / name / selector | required | the 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]
| Argument | Flag | Type | About | |
|---|---|---|---|---|
nodeIds | [id] | required | the layers to group | |
name | --name | string | the 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]
| Argument | Flag | Type | About | |
|---|---|---|---|---|
find | --in | text | required | the words to look for |
with | text | required | the words to put in their place | |
scope | id / name | only 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]
| Argument | Flag | Type | About | |
|---|---|---|---|---|
nodeIds | [id] | top-level layers, in the order to place them (default: all, in reading order) | ||
columns | --columns | number | layers per row (default: one row) | |
gap | --gap | number / [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
| Argument | Flag | Type | About | |
|---|---|---|---|---|
nodeIds | [id] | required | layers to move, in order | |
parentId | id / null | the new parent frame (default and null: the page) | ||
index | --index | number | child index in the new parent (0 is the bottom of the stack and the start of a flow) | |
toPage | --to-page | name / id | move the layers (top-level or not) onto this page instead, one undo step; instances stay linked | |
within | bool | keep 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]
| Argument | Flag | Type | About | |
|---|---|---|---|---|
script | string | required | the code; return gives the result, await works | |
readOnly | --read-only | bool | roll back every change at the end (inspections and measurements) | |
input | --input | any JSON | a value the script reads as canvas.input | |
timeoutMs | --timeout-ms | number | time 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"}]}'
| Argument | Flag | Type | About | |
|---|---|---|---|---|
styles | list | required | [{"name", "fill"}] | |
update | bool | redefine 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":[...]}]}'
| Argument | Flag | Type | About | |
|---|---|---|---|---|
styles | list | required | [{"name", "effects"}] | |
update | bool | redefine 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}]}'
| Argument | Flag | Type | About | |
|---|---|---|---|---|
styles | list | required | [{"name", "fontFamily", "fontWeight", "fontSize", ...}] | |
update | bool | redefine 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}'
| Argument | Flag | Type | About | |
|---|---|---|---|---|
query | string | required | what the photo shows | |
limit | number | results (default 6, at most 20) | ||
sheet | path | also 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]
| Argument | Flag | Type | About | |
|---|---|---|---|---|
action | list / search / info / used | default: 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 | ||
missing | bool | used: only the families this machine lacks | ||
query | string | search: part of a family name | ||
family | string | info: the family | ||
category | string | list: sans-serif, serif, display, handwriting or monospace | ||
installed | bool | list: only families that render here now | ||
google | bool | list: only Google Fonts families | ||
limit | number | families 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}'
| Argument | Flag | Type | About | |
|---|---|---|---|---|
nodeId | id | subtree (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"}'
| Argument | Flag | Type | About | |
|---|---|---|---|---|
name | string | required | project 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"}'
| Argument | Flag | Type | About | |
|---|---|---|---|---|
projectId | string | required | project name | |
title | string | required | file 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]
| Argument | Flag | Type | About | |
|---|---|---|---|---|
nodeId | id | audit 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]
| Argument | Flag | Type | About | |
|---|---|---|---|---|
nodeIds | [id] | layers to frame, each by name, selector or id (default: the page) | ||
output | path | required | PNG file to write | |
scale | --scale | number | pixels per unit (default 1) | |
padding | --padding | number | margin in units (default 0) | |
background | --background | color | color 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 | --isolate | bool | only the named layers and what they hold, without the layers beside or over them (default: everything in the frame, as the canvas shows it) | |
sheet | bool | several 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 | --props | object | render 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
| Argument | Flag | Type | About | |
|---|---|---|---|---|
nodeId | id | required | the 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
| Argument | Flag | Type | About | |
|---|---|---|---|---|
nodeId | id | required | the node | |
depth | --depth | number | levels of children (default 1) | |
to | id | another 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]
| Argument | Flag | Type | About | |
|---|---|---|---|---|
nodeId | id / name | required | the layer | |
name | --name | string | the view's type name (default: the layer's name as a type name) | |
output | path | where 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]
| Argument | Flag | Type | About | |
|---|---|---|---|---|
nodeId | id / name | required | the design frame | |
image | path | required | a PNG of the built thing | |
scale | --scale | number | pixels per unit of the picture (default: its width over the frame's) | |
tolerance | --tolerance | 0..255 | how far a channel may be off before a pixel differs (default 8) | |
failOver | --fail-over | percent | fail when more than this share of pixels differ | |
output | path | where to write the difference picture | ||
background | color | what the frame is rendered on (default white) | ||
design | path | a 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]
| Argument | Flag | Type | About | |
|---|---|---|---|---|
format | --format | css / ts / json / dtcg | required | output format |
mode | --mode | string | one mode of each collection | |
nodeId | --node | id | infer 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
| Argument | Flag | Type | About | |
|---|---|---|---|---|
output | --out | dir | required | folder to write |
nodeId | id | export from this subtree only | ||
set | --set | id / name | a frame: export each layer directly inside it as a file named after it | |
format | --format | svg / png | with set: the file format (default svg) | |
size | --size | number | with set: the width each file is drawn for, in points, whatever size the layer has (15 for a 15 pt icon) | |
scale | --scale | number | with set and png: pixels per point (3 for @3x) | |
color | --color | current / drawn | with 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]
| Argument | Flag | Type | About | |
|---|---|---|---|---|
topic | string | tools, 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.