ud command reference

Every Figma MCP tool, verb and registry command of the ud command line, with parameters and examples.

Esta página está em inglês; a tradução está a caminho.

ud — UI Designer from the command line (CLI-001)

Usage:
  ud <tool | command | verb> [file] [--param value …] [--args '<json>' | --args -] [options]

Figma MCP tools: use_figma, get_metadata, create_new_file, whoami, get_figma_skill (0.1); get_screenshot, upload_assets, download_assets (0.2);
                 get_variable_defs, search_design_system, get_libraries (0.4)
Native tools: ud_run, ud_apply, ud_help, ud_tree, ud_render, ud_system
Registry commands: ud run <id> … or ud <id> …   (ud commands lists them)

Verbs:
  tree [file] [--node n | --query q] [--depth n]    indented layer tree
  inspect <target> [--file f] [--json]                one node, fully
  find --query '<selector>' [file]                    ids of matching nodes
  find --text t [--in text,names,components,styles,variables] [--regex]   find text and names (DOC-9)
  replace --find t --with r [--in text,names] [--regex]                    replace text in place (DOC-9)
  system [file] [--budget n] [--only variables,styles,components,scales,guidance]   design-system digest (AI-3)
  library list|add|remove|enable|import|updates|accept|search|publish   workspace libraries (VAR-7, VAR-8)
  run <id> [file] [--param value …]                   a registry command
  apply <steps.json | -> [--file f]                   several commands as one transaction ($1, $ref)
  new <name> [--template blank|mobile|web|desktop|design-system] [--dir d]
  where [file]                                        file, live or headless, actor, licence
  license status [--json] | activate <key> | deactivate   the licence ticket of ud and ud mcp (LIC-6)
  selection | select <ids…>                           the live editor's selection
  watch [file] [--json]                               live events as lines (headless: the file's new WAL groups)
  proposal list|open|review|accept|discard [id]       the editor's AI proposals (AI-5)
  render [file] [--node n | --query q | --page p] [--format png|jpg|webp|svg] [--scale s] [--out f]
         [--contents-only] [--background transparent|page|#hex] [--max-dimension n] [--region x,y,w,h] [--at point]
         [--mode collection=mode[,…]]
  export [file] --format udx|png|jpg|webp|svg [--node n | --page p] [--out dir] [--scale s] [--use-settings] [--ids]
  export [file] --format pdf [--page p | --node n] [--order position|flow] [--outline-text] [--out f.pdf]   vector PDF (EXP-1)
  export [file] --format tokens --tokens-format dtcg|css|scss|tailwind|style-dictionary|tokens-studio|swift|kotlin|flutter [--out f]
  import tokens <tokens.json> [--format dtcg|style-dictionary|tokens-studio] [--collection c]   variables from tokens (VAR-9)
  snippet <target> --language react|react-modules|tailwind|custom-element|html|css|swiftui|compose [--out f]   code for a node (DEV-2)
  codegen <target> --framework <language> [--out dir] [--dry-run]   generate files; edits outside ud:generated markers stay (DEV-3)
  codemap list|get|set|remove|suggest|resolve         components mapped to code components (DEV-4, Code Connect)
  lint [targets…] [--rules .design-lint.json] [--only a,b] [--fix] [--json]   design lint; exit 1 on errors (DEV-6)
  components usage [component] [file]                 instances here and in the workspace, detached, overrides (CMP-9)
  insert [file] --udx <file | -> [--parent p] [--x n --y n]   build nodes from UDX (ud help udx)
  replace [file] <target> --udx <file | ->            replace a subtree, keeping matching ids
  import svg <file.svg> | image <file> [--parent p]   SVG as vectors, an image as an image fill
  fonts [file] [--os] | font embed [file] --family f [--style s]
  validate [files…] [--fonts]                         schema and reader checks; --fonts: missing and OS fonts
  consolidate [file]                                  fold the WAL into the tree (hash unchanged)
  history [file] [--since seq] [--limit n]            changes by session: time, actor, summary, seq range, hash
  versions [file] | versions show <vs-…> [--udx | --out f.design]   named versions (older ones from git)
  version save "<title>" [--description d]            save a named version
  restore <seq | sha256:… | vs-…> [file]              restore a point as a new change
  prototype run [file] --flow f [--steps '…'] [--out shot.png]   play a flow headless and render the final screen (PRO-10)
  prototype flows [file] | prototype motion <node>    flows with their screens; animated interactions (get_motion_context)
  prototype export [file] [--out dir] [--flow f]   the prototype as a static site (PRO-9)
  import figma <url> [--token t] [--pages a,b] [--report r.json] [--dry-run]   a Figma file via the REST API (EXP-5)
  import sketch|penpot <file> [out.design] [--pages a,b] [--no-images] [--report r.json] [--dry-run]   a .sketch or Penpot file (EXP-8)
  import html <url> [--viewport 390,1440] [--reference]   a running page rebuilt as frames (INT-1)
  capture <url> --out shot.png [--viewport w]   a screenshot of a running page (INT-1)
  compare-live <node> <url> [file]   a frame against the running page: regions, spacing, color, font (INT-3)
  diff <a> [b] [file] [--image out.png] [--page p | --node n]      structural and visual diff (CMD-35)
  compare <a> [b] [file] [--page p | --node n] [--out dir]   frames changed since a (or since Ready for dev: a = ready),
         rendered before/after with an overlay (COL-5, DEV-5)
  comments [file] [--open] [--page p] [--node n] [--mine]   comment threads (COL-4)
  comments add --message m [--node n | --page p --x n --y n] | reply <id> | resolve <id> | react <id> <emoji> | delete <id>
  commands [--category c] | help [topic] | schema <id|tool> | plugin-api | version
  mcp [--file f] [--read-only] [--allow a,b] [--proposal id|auto] [--as name]
  mcp install [--dry-run] | skill --install [--dir d] [--only a,b] [--force] [--global]

Options: --file, --as <actor>, --json, --dry-run, --if-version <hash>, --seed <hex>, --wait <s>, --live, --no-live, --quiet,
         --workspace <dir> (where libraries are searched; else UD_WORKSPACE, the git root or the file's folder),
         --fonts <dir> (a workspace font folder; repeat; else UD_FONT_DIRS or fonts/ and assets/fonts/)
Exit codes: 0 ok, 1 command failed, 2 usage, 3 conflict, 4 licence, 5 not found, 6 unsupported.

ud tree [file] [--node n | --query q | --page p] [--depth n] [--json]
Compact indented layer tree: type, name, size, position, id (CMD-33).

ud inspect#

ud inspect <target> [--file f] [--query q] [--fields a,b] [--platform web|ios|android|flutter] [--json]
One node with every property (node.describe). The target is an id, a name path or a ud:// link.
--platform (or --fields code) adds code: the box model, CSS or platform code, Tailwind classes, variables, typography,
assets, the code-map snippet and accessibility (codegen.inspect, DEV-1).

ud find#

ud find --query '<selector>' [file] [--page p] [--json]
Ids of the nodes a selector matches (ud help selectors).
ud find --text t [file] [--in text,names,components,styles,variables] [--regex] [--case-sensitive] [--page p] [--json]
Finds text content, layer names, components, styles and variables (DOC-9, document.find).

ud replace#

ud replace [file] --find t --with r [--in text,names] [--regex] [--case-sensitive] [--page p] [--targets a,b]
Replaces text in text layers (and layer names with --in names) in place, keeping styled runs (DOC-9, document.replace).
ud replace [file] <target> --udx <file | -> [--keep-ids false]
Replaces a node and its subtree with UDX, keeping the nodes whose id attributes match (udx.replace).

ud system#

ud system [file] [--budget n] [--only variables,styles,components,scales,guidance] [--json]
The design-system digest of the file and its libraries (AI-3, system.digest): variables with modes, styles, components with
properties, scales, guidance; under --budget tokens (default 4000). Load it before designing; bind variables, use styles.

ud library#

ud library list [file] [--json]                          libraries used (status current|updates|missing) and available
ud library add <path.design | name | doc-…> [--file f]   use a workspace library (library.add)
ud library import <library> <name|id …>                  copy components, styles, variables (+ dependencies)
ud library updates [library] | accept [library] [ids …]  review and accept library changes (VAR-8)
ud library search <query> [--entity component|variable|style|all]
ud library publish [name] [--description d] | --unpublish   mark this file as a library (document.library)
ud library remove <library> | enable <library> --enabled false
Libraries are searched under --workspace (UD_WORKSPACE, else the git root, else the file's folder) and ud.libraries.

ud run#

ud run <command-id> [file] [--param value …] [--args '<json>' | -] [--dry-run] [--if-version h] [--json]
Runs one registry command (ud <command-id> is the same).

ud apply#

ud apply <steps.json | -> [--file f] [--label l] [--dry-run] [--json]
A transaction of [{command, params, ref?}]; "$1" is the node created by step 1, "$name" the step whose ref is name.

ud new#

ud new <name> [--template blank|mobile|web|desktop|design-system] [--dir d] [--force] [--json]
Creates <name>.design (as create_new_file).
ud new <name> --from-figma <figma.com/design URL> [--token t] [--pages a,b] [--no-images]: a new file holding the Figma file (EXP-5).

ud where#

ud where [file] [--json]
Which file a command would use, live (through the editor) or headless, the actor and the licence.

ud license#

ud license status [--json]
The plan ud and ud mcp edit with: the licence ticket the editor writes next to the ud shim (UD_LICENSE_TICKET), verified
offline. No ticket, or one that does not verify, is the Free plan: reading, rendering, exports and comments work; changes
exit 4.
ud license activate <key | ->
Verifies a licence key offline and writes the ticket; the editor confirms it with the licence server when it starts.
When offline verification fails, run UI Designer: Sign In in VS Code.
ud license deactivate
Removes the ticket.

ud selection#

ud selection [file] [--json]
The live editor's selection (needs a live editor).

ud watch#

ud watch [file] [--json]
Prints each committed change of the live editor as a line until interrupted or the editor closes the file (CMD-37);
--json prints {seq, hash, actor, source, label, events} per group. Without an editor, prints the groups appended to
the file's WAL as they land (a rewrite of the file prints one line with reset: true).

ud proposal#

ud proposal list [file] [--json]                     the editor's proposals (AI panel turns, --proposal auto sessions)
ud proposal review <id> [--images] [--json]           change list, changed frames, conflicts (ai-agents §6.5)
ud proposal accept <id> [--use-proposal-values '[{"nodeId": …, "property": …}]']   apply as one undo step
ud proposal discard <id>                              drop it
ud proposal open [--label l]                          fork the document (writes with UD_PROPOSAL=<id> go to it)
Only the live editor holds proposals.

ud render#

ud render [file] [--node n | --query q | --page p] [--format png|jpg|webp|svg|pdf] [--scale s] [--out f] [--contents-only]
          [--background transparent|page|#hex] [--max-dimension n] [--region x,y,w,h] [--quality 0-1] [--json]
Renders a node (default: the selection, else the first page) with the reference renderer (CMD-32). Without --contents-only a
node is drawn with what overlaps it inside its bounds. Prints the written path (default: a temporary file); --json prints
{path, width, height, mime}. --at <seq|sha256:…|vs-…> renders the document as it was then. --mode color=Dark[,space=Compact]
renders with those variable modes (VAR-6): explicit modes at the rendered node or page; frames inside that choose a mode keep it.

ud export#

ud export [file] --format tokens --tokens-format dtcg|css|scss|tailwind|style-dictionary|tokens-studio|swift|kotlin|flutter [--out f|dir]
          [--collections a,b] [--modes a,b]
Design tokens from the variables (tokens.export, VAR-9); prints them without --out.
ud export [file] --format udx|png|jpg|webp|svg [--node n | --nodes a,b | --query q | --page p] [--out dir] [--scale s] [--use-settings] [--ids]
udx: prints the UDX (or writes --out). Images: one file per export setting of the node (without --format, or with
--use-settings), else the format at --scale; written into --out (default: the working folder).
ud export [file] --format pdf [--page p | --node n | --nodes a,b] [--order position|flow] [--outline-text] [--out f.pdf|dir]
A vector PDF with embedded, subset fonts (EXP-1): a page gives one PDF page per top-level frame, in reading order
(position) or along the prototype flows (flow); a node gives one page. --outline-text draws text as outlines. Blurs and
shadows are rasterised at 2x; text in fonts whose licence forbids embedding is outlined, with a warning.

ud import#

ud import tokens <tokens.json | -> [--format dtcg|style-dictionary|tokens-studio] [--collection c] [--dry-run] [file]
Creates or updates collections, modes and variables from design tokens (tokens.import, VAR-9).
ud import svg <file.svg> [--parent p] [--x n --y n] [--name n] [file]
ud import image <file> [--parent p] [--x n --y n] [file]
SVG becomes frames, shapes and vectors (EXP-4); an image becomes a rectangle with an image fill.
ud import figma <figma.com/design URL> [file] [--token t | FIGMA_TOKEN] [--pages a,b] [--depth n] [--no-images] [--report out.json] [--dry-run]
Imports a Figma file through the REST API (EXP-5): one transaction per page, then the report (approximated ratio, issues).
ud import sketch <file.sketch> [out.design] [--pages a,b] [--no-images] [--report r.json] [--dry-run]
ud import penpot <file.penpot | file.zip> [out.design] [--pages a,b] [--no-images] [--report r.json] [--dry-run]
Imports a Sketch document or a Penpot export (EXP-8): one transaction per page, then the same report; --dry-run lists
the pages; an out.design that does not exist is created.
ud import html <url | page.html | folder> [file] [--viewport 390,1440] [--reference] [--full-page false] [--selector s] [--page p] [--x n --y n]
Captures the page with headless Chromium (UD_CHROMIUM) and rebuilds it as frames, one per viewport (INT-1); --reference
names the frame "Reference: <route>" and locks it.

ud snippet#

ud snippet <target> [file] --language react|react-modules|tailwind|custom-element|html|css|swiftui|compose [--out f|dir]
          [--component-name N] [--no-code-map] [--options '<json>'] [--json]
Code for a node (codegen.snippet, DEV-2): prints it, or writes --out (a folder gets every file: Name.tsx, Name.module.css …).
Mapped instances (ud codemap) become their code components.

ud codegen#

ud codegen <target> [file] --framework <language> [--out dir] [--dry-run] [--component-name N] [--json]
Writes the generated files into --out (default: the working folder) with image assets under assets/ (codegen.generate,
DEV-3). The code sits between ud:generated <id> start/end markers: regenerating replaces only that, so edits outside
the markers stay; a file without the markers is left alone. --dry-run prints a unified diff per file.

ud codemap#

ud codemap list [file]                           components, mapped or not, with instance counts
ud codemap set <component> <componentName> [source] [--label React] [--props '<json>'] [--template t]
ud codemap get [node] | resolve <instance> | remove <component>
ud codemap suggest [component] [--min 0.4]          code components of the workspace that look like the design's
The map lives on the component (codeMap) and in the ud.codeMap setting (DEV-4, Code Connect).

ud lint#

ud lint [targets…] [file] [--rules .design-lint.json] [--only rule,rule] [--fix [--dry-run]] [--json]
Checks detached instances, raw colours, missing text styles and auto layout, contrast (per mode), touch targets, the
spacing scale, unnamed layers, alt text, accessible names, dormant overrides, inert reactions and missing variable
values (lint.run, DEV-6). Without --rules the .design-lint.json next to the design (or above it) is used. --fix applies
the fixable findings first (lint.fix). Exit 1 when an error-level finding remains.

ud components#

ud components usage [component] [file] [--json]
For each component of this file: instances here and in the workspace's design files that use it as a library,
detached copies and the most used overrides (components.usage, CMP-9).

ud insert#

ud insert [file] --udx <file | -> [--parent p] [--after n] [--x n --y n] [--keep-ids]
Builds nodes from UDX (CLI-001 §7, udx.insert). Image src paths are read relative to the design file, or to the UDX file.

ud fonts#

ud fonts [file] [--os] [--json]
The font index: embedded (document), workspace (--fonts, UD_FONT_DIRS, fonts/), bundled and, with --os, system fonts;
and the fonts the design uses that resolve nowhere.

ud validate#

ud validate [files…] [--json]
Checks files against schemas/design-1.0.schema.json and the reader's rules (FMT-001 §9). Exit 1 when one is invalid.
ud validate --fonts [files…] [--json]
Lists text nodes whose font is missing (exit 1) or resolves to an OS font (TXT-6). UD_OS_FONTS=0 skips the OS folders.

ud consolidate#

ud consolidate [file] [--dry-run] [--json]
Rewrites the file with the WAL folded into the tree; the state hash is unchanged (FMT-001 §7).

ud history#

ud history [file] [--since seq] [--limit n] [--json]
The WAL's changes grouped by transaction and by session (COL-1): time, actor, summary or undo label, seq range and the
state hash after each group. Preview a point with ud render --at <seq|hash|vs-…>; restore it with ud restore.

ud versions#

ud versions [file] [--json]
Named versions, oldest first (COL-2).
ud versions show <vs-…> [file] [--json | --udx [--page p] | --out file.design]
The document at a version: from the WAL, else from the git history of the file (the last commit whose WAL still holds
the version.save event), checked against its treeHash. --out writes it as a consolidated .design file.

ud version#

ud version [--json]
The CLI, design format and Plugin API coverage versions (also ud --version).
ud version save "<title>" [file] [--description d] [--json]
Saves a named version (version.save, COL-2).

ud restore#

ud restore <seq | sha256:… | vs-…> [file] [--dry-run] [--json]
Makes the document what it was at that point, as one new undoable change (history.restore).

ud prototype#

ud prototype run [file] --flow <name|fl-…> [--node frame] [--steps 'click:"Sign in";wait:300;back'] [--out shot.png] [--format png|jpg|webp|svg]
          [--scale s] [--mode c=m] [--no-render] [--json]
Plays the flow headless (PRO-10) and renders the final screen. Steps: click|hover|press|release:"Name" (a layer's name, its text,
or its id) or x,y in screen px; drag:"Name",dx,dy; scroll:[target,]dx,dy; key:Enter; wait:ms (runs after-delay timers); timeout
(fires the next one); back; outside (click outside the top overlay); unhover; restart. Prints each step's screen, the final
screen with its frame counter (3 / 5) and the image path; --json prints the plan (screens, steps, final, hotspots).
ud prototype flows [file] [--json]
The flows with the screens they reach. ud prototype motion <node> [file]: get_motion_context.
ud render --steps '…' [--flow f] is the same as ud prototype run (CMD-32).
ud prototype export [file] [--out dir] [--flow f]… [--page p]… [--no-fonts] [--base-url /path/] [--json]
Writes the prototype as a static site (PRO-9): index.html, player.js, lib/, state.json, assets/, fonts/; serve it over HTTP.

ud capture#

ud capture <url | page.html> --out shot.png [--viewport 1440] [--height 900] [--full-page] [--json]
A PNG screenshot of a running page with headless Chromium (page.capture, INT-1); no design file needed.

ud compare-live#

ud compare-live <node> <url> [file] [--viewport w] [--tolerance px] [--json]
Compares a frame with the running page (document.compareLive, INT-3): changed pixel regions, a difference overlay, and the
spacing, color and font mismatches of the frame's texts matched by content.

ud diff#

ud diff <a> [b] [file] [--image out.png] [--page p | --node n] [--scale s] [--json]
Compares two versions (CMD-35): a and b are WAL points (12, sha256:…, vs-…), current (b's default), .design files, git
revisions of the file (HEAD~1) or rev:path. Prints one line per change (+ created, - deleted, ~ changed, > moved, with renames
and text edits); --json the change list and summary. --image writes the overlay (changed regions outlined in red) and
<out>-before.png, <out>-after.png of the page (or node) at both points.

ud compare#

ud compare <a> [b] [file] [--page p | --node n] [--scope changed|all] [--out dir] [--scale s] [--no-images] [--json]
Visual compare (COL-5, DEV-5): the top-level frames added, removed or changed between a and b (points as in ud diff:
12, sha256:…, vs-…, current, file.design, HEAD~1, rev:path), each rendered at both points: <frame>-before.png,
<frame>-after.png and <frame>.png, the overlay with the changed regions outlined in red, under
<name>.design.assets/compare/<hash-a>-<hash-b>/ (or --out). a = ready compares every frame marked Ready for dev with
itself when it was marked. --scope all renders every frame and reports pixel-only changes (styles, variables, main
components) too. --json prints {frames: [{nodeId, name, change, before, after, overlay, regions}], summary}.

ud comments#

ud comments [file] [--open] [--page p] [--node n] [--mine] [--json]
The comment threads with their replies (comment.list, COL-4): open or resolved, author, time, anchor, review meta.
ud comments add [file] --message m [--node n [--x dx --y dy] | --page p --x n --y n] [--mentions a,b]
                [--category c --severity info|warning|error --finding-id id]
ud comments reply <thread> --message m | update <id> --message m | react <id> <emoji> [--on false]
ud comments resolve <thread> | reopen <thread> | delete <id>
@Name and @"Two Words" in a message are mentions. ud run comment.* takes the same parameters.

ud commands#

ud commands [--category c] [--json]
Every registry command and tool, with since and flags.

ud mcp#

ud mcp [--file f] [--read-only] [--allow a,b] [--proposal id|auto] [--as name] [--fonts dir]
A stdio MCP server named ui-designer (CMD-7). It keeps folded documents, the text engine and the fonts warm between
calls, and serves the single-use loopback URLs of get_screenshot, download_assets and upload_assets (127.0.0.1 only).
--proposal <id> (or UD_PROPOSAL) sends every call to that proposal of the live editor; --proposal auto opens one on the
session's first write (whoami and ud_run where report it; headless, writes go to the file and whoami says why).
ud mcp install [--dry-run] [--proposal auto] [--file f]
Adds the server to .mcp.json of the working folder.

ud select#

ud select <id | name path …> [--query q] [--file f]
Sets the live editor's selection (needs a live editor).

ud help#

ud help [command | tool | verb | topic]
Topics: commands, tools, plugin-api, selectors, udx, skill:<name>.

ud schema#

ud schema <command | tool>
Parameter (and result) JSON Schemas.

ud plugin-api#

ud plugin-api [--json]
The Plugin API coverage table (CMD-14).

ud skill#

ud skill [--json]
Lists the bundled skills.
ud skill --install [--dir d] [--only a,b] [--force] [--global] [--dry-run]
Copies them into .claude/skills/ with a .ud-skill.json manifest (AI-001 §3.8).

ud font#

ud font embed [file] --family f [--style s] [--dry-run] [--json]
Copies a font file into <name>.design.assets/ and registers it (asset.add, FMT-001 §8.3). Refused when the font's OS/2
fsType forbids embedding (D22: only 0 or bit 3 is embedded); exit 1 when nothing was embedded.

Registry commands#

Every command of the editor is a registry command: the editor, the context menus, ud, use_figma and the MCP server all run the same definitions. Run one with ud <id> [file] --param value … or ud run <id> …; ud help <id> prints this help and ud schema <id> the JSON Schema. Commands marked selection act on the editor’s selection when no target is given.

Document#

document.update#

Update Document. Rename the document or change its colour profile.

Since 0.1 · mutates · licence paid

Changes the document’s own properties (FMT-001 §4.2): the name shown in the title bar and the colour profile. Since 0.4, –library publishes the file as a workspace library (FMT-001 §4.2, VAR-7).

ud document.update --name "Checkout" --colorProfile SRGB
ud document.update --library '{"name": "Starter DS", "description": "Tokens and base components"}'

document.info#

Document Info. The document id, name, state hash, sequence number and the number of pages and nodes.

Since 0.1 · read-only · licence read

Prints what identifies the document and its current state: the id, the name, the state hash of FMT-001 §6.9 (what –if-version takes), the last event number and the counts of pages and nodes.

Takes no parameters.

ud document.info --json

document.find#

Find. Find text, layer names, components, styles and variables across pages (DOC-9).

Since 0.4 · read-only · licence read

Searches the document (DOC-9): –in text (TEXT characters), names (layer names), components (names and descriptions), styles and variables (names and descriptions); default text and names. –regex treats –text as a regular expression; matching ignores case unless –caseSensitive. Each match has kind, id, page, name, a snippet and the range of the first hit. Without –text every item of the chosen kinds is listed.

ud find --text "Sign in" --in text,names
ud document.find --text "^Button" --regex --in components --json

document.replace#

Replace. Replace text in text layers (and optionally layer names) across the document, keeping styles.

Since 0.4 · mutates · licence paid

Replaces every occurrence in place (DOC-9): text content keeps its styled runs; –in names also renames layers. –regex enables groups ($1) in –replace; –targets limits to some nodes; –page to one page. One undo step.

ud replace --find "Sign in" --with "Log in"
ud document.replace --find "Button (\d+)" --replace "Action $1" --regex --in names

document.compareLive#

Compare with Live Page. Compare a frame with the running page: a screenshot, a pixel overlay, and the spacing, colour and font mismatches.

Since 0.8 · read-only · licence read · writes files · network

INT-3. Captures the URL in headless Chromium at the frame’s width (or viewport) and height, renders the frame, and compares them: regions of differing pixels (the NFR-8 tolerance, 8 px cells merged), a difference overlay image, and the frame’s texts matched with the page’s by content: spacing (position off by more than tolerance px), color (text colour) and font (family, size, style) mismatches, each with the node id, expected (design) and actual (page). The screenshot, render and overlay PNGs are written to a temporary folder.

ud compare-live "Home/Desktop" http://localhost:5173/
ud document.compareLive --node nd-0123456789ab --url http://localhost:5173/ --viewport 1440

system.digest#

Design System Digest. A compact digest of the file’s and its libraries’ variables, styles, components, scales and guidance.

Since 0.4 · read-only · licence read

What agents load first (AI-3, ud system): variables by collection with modes (values per mode, a|b when they differ), styles by type, components with variants and properties, spacing/radius/type scales, and guidance from descriptions. –budget caps the text in tokens (default 4000; lists are cut with “…(+n)”); –only picks parts (variables, styles, components, scales, guidance). The json member has everything uncut.

ud system
ud system --budget 2000 --only variables,components
ud system.digest --json

lint.run#

Lint Design. Check the design against the lint rules: tokens, styles, auto layout, contrast, touch targets, names, alt text.

Since 0.6 · read-only · licence read

CMD-36: detached-instance (warning), raw-color (warning), text-style (warning), missing-auto-layout (warning), contrast (error), touch-target (warning), spacing-scale (warning), unnamed-layer (info), missing-alt-text (warning), missing-accessible-name (warning), dormant-override (info), inert-reaction (warning), missing-variable-value (warning), noise-on-text (warning), text-on-path-overflow (warning). Each finding has rule, severity, nodeId, name, page, message and, for mechanical ones, fix {command, params, label} (lint.fix applies them). Levels and options come from .design-lint.json next to the design file or above it: {“rules”: {“unnamed-layer”: “off”, “contrast”: “error”, “touch-target”: {“level”: “warn”, “options”: {“min”: 48}}}, “ignore”: [“frame[name^="Scratch"]”], “spacingScale”: [0, 4, 8, 12, 16, 24, 32]}. ud lint exits 1 when there are errors.

ud lint.run
ud lint "Screens/Login" --json
ud lint.run --rules '["contrast", "touch-target"]'

lint.fix#

Fix Lint Findings. Apply the mechanical fixes of lint findings (bind raw colours, apply text styles, rename, reset dormant overrides).

Since 0.6 · mutates · licence paid

CMD-36: runs the rules like lint.run and applies each finding’s fix in one transaction (one undo step): raw-color binds the paint to its variable (node.bind), text-style applies the matching style (style.apply), spacing-scale snaps to the nearest step, unnamed-layer renames from the first text, dormant-override resets the override. A fix that fails is reported and the others are kept. ud lint –fix runs it.

ud lint.fix --rules '["raw-color", "text-style"]'
ud lint "Screens/Login" --fix

Pages#

page.create#

Create Page. Add a page, last or after a given page.

Since 0.1 · mutates · licence paid

Creates a page. Without –name it is called “Page N”; without –after it goes last.

ud page.create --name "Components" --after "Screens"

page.update#

Update Page. Rename a page or set its canvas background.

Since 0.1 · mutates · licence paid

Changes a page’s name or backgrounds (a paint list; the canvas colour).

ud page.update --page Screens --name "Mobile screens"

page.reorder#

Reorder Page. Move a page after another page or to a position.

Since 0.1 · mutates · licence paid

Moves a page in the page list: –after or –index (0 is first). Without either it goes last.

ud page.reorder --page Components --index 0

page.delete#

Delete Page. Delete a page and everything on it.

Since 0.1 · mutates · licence paid

Deletes a page with all its nodes. The last page cannot be deleted.

ud page.delete --page "Old screens"

page.list#

List Pages. The pages in order, with the number of top-level nodes on each.

Since 0.1 · read-only · licence read

Lists the pages of the document in their order.

Takes no parameters.

ud page.list --json

guide.add#

Add Guide. Add a ruler guide to a page or a frame (what dragging from a ruler does).

Since 0.3 · mutates · licence paid

CAN-8: a guide is {axis, offset}: axis X is a vertical line at x = offset, Y a horizontal line at y = offset, in page units on a page and from the frame’s top-left corner on a frame. Guides are stored in the file.

ud guide.add --page Screens --axis X --offset 24
ud guide.add --node "Screens/Login" --axis Y --offset 120

guide.move#

Move Guide. Move a ruler guide of a page or a frame to a new offset.

Since 0.3 · mutates · licence paid

Sets the offset of the guide at –index (its position in guide.list).

ud guide.move --page Screens --index 0 --offset 32

guide.remove#

Remove Guide. Remove a ruler guide from a page or a frame.

Since 0.3 · mutates · licence paid

Removes the guide at –index; the later guides move up one index.

ud guide.remove --node "Screens/Login" --index 1

guide.list#

List Guides. The ruler guides of a page or a frame, in index order.

Since 0.3 · read-only · licence read

Lists {axis, offset} of each guide; the index is the position in the list.

ud guide.list --page Screens --json

Nodes#

node.create#

Create Node. Create a frame, group, section, shape, text, vector or boolean operation under a page or a container node.

Since 0.1 · mutates · licence paid

Creates one node of a 0.2 type (FRAME, GROUP, SECTION, RECTANGLE, ELLIPSE, LINE, POLYGON, STAR, TEXT, VECTOR, BOOLEAN_OPERATION). Any stored property of FMT-001 §4.4 and §4.6 may be given besides the common ones; a FRAME without –fills starts white, as the Frame tool makes it. A TEXT takes –characters, –fontName, –fontSize and the other text properties, and is named after its text. A VECTOR takes –vectorPaths (path data is normalised to absolute M L C Z). A BOOLEAN_OPERATION takes –children (nodes of one parent, which move into it keeping their positions) and –booleanOperation; without –fills or –strokes it takes the bottom child’s paints. An image is a RECTANGLE with an image fill: use image.insert. Without –parent the node goes on the first page; without –after it goes on top.

ud node.create --type FRAME --name Card --parent "Screens/Login" --x 24 --y 120 --width 342 --height 200
ud node.create --type RECTANGLE --parent nd-4e6a8c0d2f1b --fills '[{"type":"SOLID","color":{"r":0.3,"g":0.27,"b":0.9}}]'
ud node.create --type TEXT --parent "Screens/Login" --characters "Welcome back" --fontName '{"family":"Inter","style":"Semi Bold"}' --fontSize 28
ud node.create --type BOOLEAN_OPERATION --booleanOperation SUBTRACT --children '["nd-7b9d1f3a5c4e","nd-8c0e2a4b6d5f"]'

node.update#

Update Node Properties. Merge stored properties into nodes (the general setter behind the Plugin API).

Since 0.1 · mutates · licence paid · selection

Applies a merge patch (FMT-001 §5.9) of stored properties to each target: a member set to null is removed, arrays replace. type, parent, index and id cannot be set here; use node.reparent and node.reorder.

ud node.update --node "Screens/Login/Button" --set '{"name":"Primary button","cornerRadius":12}'
ud node.update --query 'rectangle' --set '{"strokeWeight":2}'

node.rename#

Rename Node. Rename one node.

Since 0.1 · mutates · licence paid · selection

Sets the layer name of one node.

ud node.rename --node nd-9d1f3b5c7e6a --name "Sign in button"

node.move#

Move. Set the position of nodes (–to) or nudge them (–by), within their parent.

Since 0.1 · mutates · licence paid · selection

Changes x and y relative to the parent; it never re-parents (that is node.reparent). –by is what a drag or an arrow-key nudge does (CAN-3).

ud node.move --node "Screens/Login/Button" --to '{"x":24,"y":480}'
ud node.move --query 'frame[name="Login"] > rectangle' --by '{"x":0,"y":-8}'

node.resize#

Resize. Set the width and/or height of nodes, keeping the top-left corner or the centre in place.

Since 0.1 · mutates · licence paid · selection

Sets width and height. –anchor center keeps the centre where it is (Alt-resize, CAN-3). Resizing a frame moves and resizes its children by their constraints (LAY-1; children in auto layout flow are laid out by the frame instead); –ignoreConstraints leaves them where they are (Ctrl held while resizing). A hug or fill axis that is resized becomes fixed.

ud node.resize --node "Screens/Login/Avatar" --width 96 --height 96 --anchor center
ud node.resize --node "Screens/Login" --width 1440 --ignoreConstraints

node.rotate#

Rotate. Set the rotation of nodes in degrees.

Since 0.1 · mutates · licence paid · selection

Sets the rotation (counter-clockwise positive, as in Figma) in the range -180 to 180.

ud node.rotate --node "Screens/Login/Avatar" --angle 45

node.setVisible#

Show or Hide. Show or hide nodes.

Since 0.1 · mutates · licence paid · selection

Sets the visibility (the eye in the layers panel).

ud node.setVisible --nodes '["nd-5f7b9d1e3a2c"]' --visible false

node.setLocked#

Lock or Unlock. Lock or unlock nodes against canvas edits.

Since 0.1 · mutates · licence paid · selection

Sets the lock (the padlock in the layers panel). Locked nodes are skipped by canvas selection.

ud node.setLocked --query 'frame[name="Login"]' --locked true

node.reparent#

Move into. Move nodes into another page or container, keeping their place on the canvas.

Since 0.1 · mutates · licence paid · selection

Re-parents nodes (FMT-001 node.move). With –keepPosition (the default) x and y are recomputed so the node does not move visually: at 0.1 parents translate but do not rotate their children. –index, –after or –before set the place among the new siblings; otherwise the node goes on top.

ud node.reparent --node "Screens/Login/Avatar" --parent "Screens/Login/Form"
ud node.reparent --nodes '["nd-7b9d1f3a5c4e","nd-8c0e2a4b6d5f"]' --parent Screens --index 0 --keepPosition false

node.reorder#

Reorder. Change a node’s place among its siblings: to front or back, one step, a position, or next to a sibling.

Since 0.1 · mutates · licence paid · selection

Z-order (DOC-3): –to front|back|forward|backward, –index (0 is the back), –after or –before .

ud node.reorder --node "Screens/Login/Button" --to front
ud node.reorder --node nd-5f7b9d1e3a2c --index 0

node.delete#

Delete. Delete nodes and everything inside them.

Since 0.1 · mutates · licence paid · selection

Removes the nodes and their descendants. Undo restores them with their ids.

ud node.delete --query '[name^="Draft "]'

node.duplicate#

Duplicate. Copy nodes with everything inside them, next to the originals.

Since 0.1 · mutates · licence paid · selection

Deep-copies each node (new ids, same names) just above its original in the same parent. –offset shifts the copies.

ud node.duplicate --node "Screens/Login/Button" --offset '{"x":0,"y":64}'

node.group#

Group Selection. Wrap nodes in a new group, frame or section sized to their bounds.

Since 0.1 · mutates · licence paid · selection

Group selection (Ctrl+G), frame selection (Ctrl+Alt+G) and section selection (DOC-7): the nodes must share a parent; the new container takes the union of their bounds and the nodes move into it with their positions kept (a group’s children keep x/y in the nearest frame’s space, FMT-001 §4.4.1; a frame’s become relative to it). It is placed where the top-most of them was.

ud node.group --nodes '["nd-7b9d1f3a5c4e","nd-8c0e2a4b6d5f"]' --name Fields
ud node.group --query 'frame[name="Login"] > rectangle' --type FRAME --name Card

node.ungroup#

Ungroup. Dissolve groups, frames, sections or boolean operations: their children move up, keeping their place on the canvas.

Since 0.1 · mutates · licence paid · selection

Ungroup (Ctrl+Shift+G), “Remove frame” (DOC-7) and ungrouping a boolean operation (DRW-5): each child moves into the container’s parent at the container’s place in the z-order, with x and y adjusted so nothing moves; the container is deleted.

ud node.ungroup --node "Screens/Login/Form"

node.align#

Align. Align nodes to each other’s bounds, or to their parent.

Since 0.1 · mutates · licence paid · selection

Align left, horizontal centre, right, top, vertical centre or bottom (CAN-6). Several nodes align to the bounds of the selection (–to selection, the default); one node, or –to parent, aligns inside its parent frame.

ud node.align --query 'frame[name="Login"] > rectangle' --axis left
ud node.align --node "Screens/Login/Button" --axis hcenter --to parent

node.distribute#

Distribute Spacing. Space three or more nodes evenly between the first and the last.

Since 0.1 · mutates · licence paid · selection

Distribute horizontal or vertical spacing (CAN-6): the outermost nodes stay, the others get equal gaps.

ud node.distribute --query 'frame[name="Toolbar"] > *' --axis horizontal

node.describe#

Describe Node. One node fully: every property with defaults filled in, its children ids, page and name path.

Since 0.1 · read-only · licence read · selection

What ud inspect prints: the stored properties of FMT-001 §4.4 with the defaults of core.defaults filled in, plus children (ids, bottom first), page and path (Page/Frame/Child).

ud node.describe --node "Screens/Login/Button" --json

node.tree#

Layer Tree. The layer tree under a node, a page or the whole document: id, type, name, position, size, layout and children.

Since 0.1 · read-only · licence read

What ud tree and get_metadata read. Without –node or –page the root is the document (type DOCUMENT) with one child per page (type PAGE). –depth limits the levels below the root; rows beyond it carry childCount instead of children. Positions and sizes are the derived ones (auto layout, hug and fill, groups); layout summarises auto layout and sizing: “column gap 16 pad 24 · fixed × hug”.

ud node.tree --depth 2
ud node.tree --node "Screens/Login" --json

node.find#

Find Nodes. The ids of the nodes matching a selector, in document order.

Since 0.1 · read-only · licence read

Runs a selector of CLI-001 §6 over every page, or over –page only.

ud node.find --query 'frame[name^="Login"] > rectangle'
ud node.find --query 'ellipse' --page Screens

node.presets#

Frame Presets. The frame size presets: phones, tablets, desktops, watches, paper and social media.

Since 0.1 · read-only · licence read

Lists the presets of DRW-2 with id, name, category, width and height. node.applyPreset takes the id or the name.

Takes no parameters.

ud node.presets --json

node.applyPreset#

Apply Frame Preset. Resize frames to a preset device, paper or social media size.

Since 0.1 · mutates · licence paid · selection

Sets width and height from a preset of node.presets (DRW-2), keeping the top-left corner.

ud node.applyPreset --node "Screens/Login" --preset iphone-16

vector.setPaths#

Set Vector Paths. Replace the paths of a vector node with SVG path data.

Since 0.2 · mutates · licence paid · selection

Figma’s VectorNode.vectorPaths: each path is SVG path data in the node’s own coordinates with a winding rule. The data is normalised to absolute M, L, C and Z (relative commands, H/V, quadratics and arcs are converted). The pen tool and the vector network editor arrive in 0.2b; flatten (node.flatten) too.

ud vector.setPaths --node nd-1c3e5a7b9d0f --vectorPaths '[{"windingRule":"NONZERO","data":"M 0 0 L 24 0 L 12 18 Z"}]'

node.renameBatch#

Rename Layers. Rename several layers at once: find and replace, and a pattern with numbering ($n, $nn) and the current name ($&).

Since 0.3 · mutates · licence paid · selection

DOC-6 batch rename. For each target, in –order (selection: as given; layers: document order), the current name (its default name when it has none) goes through –find/–replace (literal, or a regular expression with –regex, where $1 refers to a group), then through –pattern, where $n is the number (from –start, default 1), $nn the number padded to two digits ($nnn to three), $& the name after find/replace, and $$ a dollar. Nodes whose name does not change are left out of the result.

ud node.renameBatch --query 'frame[name^="Card"]' --pattern 'Card $nn'
ud node.renameBatch --nodes nd-1c3e5a7b9d0f,nd-9f1b3d5c7e2a --find Btn --replace Button
ud node.renameBatch --query 'text' --pattern '$& / $n' --start 0 --order layers

section.setReady#

Mark Ready for Development. Mark sections and frames “Ready for development”, or clear the mark.

Since 0.3 · mutates · licence paid · selection

DOC-8 and DEV-5: sets devStatus (FMT-001 §4.4.8) to {type: “READY_FOR_DEV”, at, description?} on sections and frames, or removes it with –ready false. at is the time the status was set, so the compare view can find the design as it was.

ud section.setReady --node "Screens/Checkout" --ready true --description "Desktop and mobile"
ud section.setReady --query 'section' --ready false

vector.setNetwork#

Set Vector Network. Replace the vector network of a vector node (vertices, straight and Bézier segments, fill regions).

Since 0.2b · mutates · licence paid · selection

DRW-4, FMT-001 §4.6.4: the whole network is one property and an edit replaces it. Vertices are points in the node’s coordinates (optional strokeCap, strokeJoin, cornerRadius, handleMirroring); segments join two vertices, straight or with tangentStart/tangentEnd handle offsets; regions are lists of loops of segment indexes with a windingRule and optional fills. The network is validated: indexes in range, no duplicate segment, every loop chains end to end and closes; degenerate parts (zero-length segments, unused vertices) only warn. vectorPaths is derived from it. With –fit (default) the node is re-based on the network’s bounds.

ud vector.setNetwork --node nd-1c3e5a7b9d0f --network '{"vertices":[{"x":0,"y":0},{"x":24,"y":0},{"x":12,"y":18}],"segments":[{"start":0,"end":1},{"start":1,"end":2,"tangentStart":{"x":0,"y":8},"tangentEnd":{"x":6,"y":0}},{"start":2,"end":0}],"regions":[{"windingRule":"NONZERO","loops":[[0,1,2]]}]}'

vector.editNetwork#

Edit Vector Network. Apply pen-tool edits to a vector network in one step: vertices, handles, segments, splits, deletions, paint bucket.

Since 0.2b · mutates · licence paid · selection

DRW-4: the pen tool’s edits as a list applied in one event (the network is one property). Coordinates are in the node’s own space, before the fit. Ops: addVertex {x, y, handleMirroring?} moveVertex {index, x, y} setVertex {index, handleMirroring?, …} setTangent {segment, end, x, y} (the vertex’s handleMirroring — or the node’s — moves the opposite handle: ANGLE keeps its length, ANGLE_AND_LENGTH mirrors it exactly, NONE leaves it) addSegment {start, end, tangentStart?, tangentEnd?} splitSegment {segment, t} deleteVertices {indices, heal?} (heal, the default: a vertex between two segments is bridged by one segment and regions keep their loops, as Figma; else its segments go) deleteSegments {indices} (regions using them go) toggleRegion {x, y} (paint bucket: removes the region under the point, or fills the closed area there with the node’s fills; crossing segments are split first) setRegionFills {region, fills} join {all?} (the nearest open ends, or all) reverse The result has the network, the shift the fit applied, the indexes of added vertices and segments, and what each toggleRegion did.

ud vector.editNetwork --node nd-1c3e5a7b9d0f --ops '[{"op":"addVertex","x":0,"y":0},{"op":"addVertex","x":24,"y":0},{"op":"addSegment","start":0,"end":1,"tangentStart":{"x":8,"y":-10},"tangentEnd":{"x":-8,"y":-10}}]'
ud vector.editNetwork --node "Icons/Heart" --ops '[{"op":"toggleRegion","x":12,"y":12}]'

vector.flatten#

Flatten. Bake shapes, groups or boolean operations into one vector node (Ctrl+E).

Since 0.2b · mutates · licence paid · selection

DRW-5, DRW-6, FMT-001 §4.6.5: the targets (siblings) are replaced, in one undo group, by one VECTOR whose network holds their geometry: a boolean operation’s result is baked (refitted to curves within 0.05 px), shapes and vectors keep their curves, groups contribute every child. The new node takes the top node’s name, appearance and paints (a group’s from its top child) and its place in the z-order; children painted differently keep their fills on their regions. Text is not flattened until 0.3. The vector gets a new id (node.delete + node.create).

ud vector.flatten --node "Icons/Badge/Subtract"
ud vector.flatten --nodes '["nd-7b9d1f3a5c4e","nd-8c0e2a4b6d5f"]'

vector.outlineStroke#

Outline Stroke. Turn strokes into filled vector geometry (Ctrl+Shift+O).

Since 0.2b · mutates · licence paid · selection

DRW-6: each target’s stroke — weight, alignment, caps, joins, miter limit, dashes, arrowheads — becomes the fill of a new VECTOR (refitted to curves within 0.05 px) whose fills are the stroke paints and which has no stroke. A node without fills is replaced by it (new id, same name and place); a node with fills keeps them, loses its strokes and gets the outline just above it. –keep leaves the node as it was (the Plugin API’s outlineStroke()). Nodes without a visible stroke are skipped with a warning. Returns the new vectors.

ud vector.outlineStroke --node "Icons/Arrow"
ud vector.outlineStroke --query 'vector[name^="Line"]' --keep true

vector.offset#

Offset Path. Grow or shrink the outline of shapes by a distance, with miter, round or bevel corners.

Since 0.2b · mutates · licence paid · selection

DRW-6: the fill area of each target moves outwards by –distance px (inwards when negative); corners that open get the –join (MITER, limited by –miterLimit, default 4, then bevelled; ROUND; BEVEL). A vector is changed in place (its network replaced, refitted to curves within 0.05 px, re-based on its bounds); any other shape becomes a vector with the same appearance (new id). An open path is offset as a stroke of width 2 × |distance|. A shape shrunk past its thickness is left empty, with a warning.

ud vector.offset --node "Icons/Star" --distance 4 --join ROUND
ud vector.offset --node nd-1c3e5a7b9d0f --distance -2

vector.simplify#

Simplify Path. Reduce the points of vector paths while keeping their shape within a tolerance.

Since 0.2b · mutates · licence paid · selection

DRW-6: every chain of segments between corners, ends and branch points is simplified within –tolerance px (default 0.5): straight runs drop points with Ramer–Douglas–Peucker, curved runs are flattened and refitted with as few Bézier segments as fit (Schneider). Corners (handles turning more than 10°) and regions are kept.

ud vector.simplify --node "Icons/Scribble" --tolerance 1

vector.join#

Join Paths. Join the open ends of vector paths, nearest first.

Since 0.2b · mutates · licence paid · selection

DRW-6: open ends (vertices used by one segment) are joined in pairs, nearest pair first: ends closer than 0.01 px merge into one vertex, others get a straight segment. A vector without regions whose join closes a loop gets the closed areas as fill regions, as a path closed with the pen is filled.

ud vector.join --node "Icons/Open path"

vector.reverse#

Reverse Path Direction. Reverse the direction of vector paths (where dashes start, which end a path begins at).

Since 0.2b · mutates · licence paid · selection

DRW-6: every segment is walked the other way (start and end, and their handles, swapped; segments and vertices listed in reverse order) and every region loop is reversed. The shape and its fills do not change; dash patterns start from the other end.

ud vector.reverse --node "Icons/Arrow"

boolean.create#

Boolean Operation. Combine nodes into a live boolean operation: union, subtract, intersect or exclude.

Since 0.2b · mutates · licence paid · selection

DRW-5, FMT-001 §4.6.5: the targets (siblings) move into a new BOOLEAN_OPERATION placed where the top-most of them was; they stay editable and keep their positions on the canvas. The result is computed live from the children in paint order, bottom-up: SUBTRACT removes every later child from the bottom one, EXCLUDE keeps what an odd number of children cover. The node takes the bottom child’s fills and strokes (which paint the result) and is named after the operation unless –name is given. Ungroup it with node.ungroup; bake it with vector.flatten.

ud boolean.create --nodes '["nd-7b9d1f3a5c4e","nd-8c0e2a4b6d5f"]' --operation SUBTRACT
ud boolean.create --query 'frame[name="Icon"] > ellipse' --operation UNION --name Blob

boolean.setOperation#

Set Boolean Operation. Change the operation of boolean operation nodes.

Since 0.2b · mutates · licence paid · selection

DRW-5: UNION, SUBTRACT, INTERSECT or EXCLUDE. A node still carrying its default name (Union, Subtract, Intersect, Exclude) is renamed after the new operation.

ud boolean.setOperation --node "Icons/Badge/Union" --operation EXCLUDE

node.rescale#

Scale. Scale nodes with their properties: size, position, strokes, effects, radii, text and vector coordinates (K).

Since 0.2b · mutates · licence paid · selection

DRW-9, Figma’s rescale(): every node of each target’s subtree is scaled by –factor — size, stroke weights and dash patterns, effect radii, spreads and offsets, corner radii, font sizes with letter spacing and line height in pixels, paragraph spacing, auto-layout padding and gaps, layout grids, vector network coordinates and vector paths. The target keeps –origin fixed (a page point; default its top-left corner); positions inside it scale with it.

ud node.rescale --node "Screens/Login/Card" --factor 2
ud node.rescale --query 'frame[name="Icon"]' --factor 0.5 --origin '{"x":100,"y":100}'

node.setAccessibility#

Set Accessibility. Set a node’s accessibility metadata: role, name, description, heading level, focus order, alt text, decorative.

Since 0.6 · mutates · licence paid · selection · aliases a11y.set

DEV-8: the accessibility object of FMT-001 §4.4.8 ({role, name, description, headingLevel 1-6, focusOrder, altText, decorative}). Values merge into what is stored; null removes one. Code generation uses it (headings become h1-h6, roles pick elements, alt text and names become alt and aria-label) and ud lint checks it (missing-alt-text, missing-accessible-name).

ud node.setAccessibility --node "Screens/Login/Title" --role heading --headingLevel 1
ud node.setAccessibility --node "Screens/Login/Logo" --altText "Shop logo"
ud node.setAccessibility --query 'rectangle[name="Divider"]' --decorative true

node.setStatus#

Set Dev Status. Mark frames, sections and components Ready for development or Completed, or clear the mark.

Since 0.6 · mutates · licence paid · selection

DEV-5: sets devStatus {type, description?, at} (FMT-001 §4.4.8) on frames, sections, components and component sets; –status null clears it. at is the time it was set, so the compare view can show what changed since. section.setReady is the older form for READY_FOR_DEV.

ud node.setStatus --node "Screens/Checkout" --status READY_FOR_DEV --description "Desktop and mobile"
ud node.setStatus --node "Screens/Checkout" --status COMPLETED
ud node.setStatus --node "Screens/Checkout" --status null

annotation.add#

Add Annotation. Attach a developer note to nodes, with pinned properties and a category.

Since 0.6 · mutates · licence paid · selection

DEV-7: appends {label, labelMarkdown, properties, categoryId} (Figma’s shape, FMT-001 §4.4.8) to the nodes’ annotations. –category takes a category id or label (built in: behaviour, accessibility, interaction).

ud annotation.add --node "Screens/Login/Sign in" --label "Disabled until both fields are valid" --category behaviour
ud annotation.add --node "Screens/Login/Card" --properties '[{"type": "width"}, {"type": "cornerRadius"}]'

annotation.set#

Edit Annotation. Change one annotation of a node (label, markdown, pinned properties, category).

Since 0.6 · mutates · licence paid · selection

DEV-7: edits annotations[index] of one node; null removes a member.

ud annotation.set --node "Screens/Login/Sign in" --index 0 --label "Disabled until the form is valid"

annotation.remove#

Remove Annotation. Remove one annotation (by index) or all annotations of nodes.

Since 0.6 · mutates · licence paid · selection

DEV-7: without –index every annotation of the nodes goes.

ud annotation.remove --node "Screens/Login/Sign in" --index 0
ud annotation.remove --query 'frame'

annotation.categories#

Annotation Categories. The annotation categories of the document (built in: behaviour, accessibility, interaction).

Since 0.6 · read-only · licence read

DEV-7, FMT-001 §4.2 annotationCategories: id, label, colour and order of each category.

Takes no parameters.

ud annotation.categories

annotation.addCategory#

Add Annotation Category. Add an annotation category with a label and colour.

Since 0.6 · mutates · licence paid

DEV-7: adds a category (an- id) to document.annotationCategories; the built-in ones are kept.

ud annotation.addCategory --label Content --color teal

annotation.removeCategory#

Remove Annotation Category. Remove an annotation category; annotations in it keep their text and lose the category.

Since 0.6 · mutates · licence paid

DEV-7: removes the category from document.annotationCategories and its id from the annotations that used it.

ud annotation.removeCategory --category Content

trace.add#

Add Trace. Link nodes to a Project Board item (REQ-n, #n) of a .pb board, or to a Software Board element of a .uml model.

Since 0.6 · mutates · licence paid · selection

INT-1: appends {file, item} to the nodes’ traces (FMT-001 §4.4.8). file is the .pb board, relative to the design file; item is the issue number (#12), its requirement id (DEV-4, the first word of the title) or its id (iss-…). INT-4: with –kind uml, file is a Software Board model (.uml) and item an element id (el-…) of a Component, Class, Interface, Use case or Actor; the trace is stored as {kind: “uml”, file, item}. –kind defaults to the file’s extension. trace.list reads the files and shows each item’s title and state, or each element’s type and name.

ud trace.add --node "Screens/Checkout" --file planning.pb --item "#42"
ud trace.add --node "Screens/Login" --file planning.pb --item DEV-4
ud trace.add --node "Screens/Login" --kind uml --file ui-designer.uml --item el-4f0c2a9d1b7e

trace.remove#

Remove Trace. Remove traces from nodes: one item, every item of a board or model, every trace of a kind, or all.

Since 0.6 · mutates · licence paid · selection

INT-1: removes the traces matching –kind, –file and –item (all optional; none removes all).

ud trace.remove --node "Screens/Checkout" --file planning.pb --item "#42"
ud trace.remove --node "Screens/Checkout" --kind uml

trace.list#

List Traces. The Project Board items and Software Board elements nodes trace to, with titles, states, types and names read from the files.

Since 0.6 · read-only · licence read

INT-1: every trace of the node (or of the document), with the item’s title and state folded from the .pb board (tree issues and WAL issue events). INT-4: a uml trace shows the element’s type, name and qualified name folded from the .uml model (tree elements and WAL element events). A file that cannot be read or an item it does not have is marked missing.

ud trace.list
ud trace.list --node "Screens/Checkout"

trace.find#

Find Traced Nodes. The nodes of the document that trace to a Project Board item or a Software Board element (the reverse of trace.list).

Since 1.2 · read-only · licence read

INT-4: the reverse lookup: every node whose traces name –item (with –kind, default pb, and –file when given), with its name, type and page. Software Board, or an agent, asks it which frames realise a model element.

ud trace.find --kind uml --item el-4f0c2a9d1b7e
ud trace.find --file planning.pb --item DEV-4

Text#

text.set#

Set Text. Replace the characters of text nodes, dropping or cutting their styled runs.

Since 0.2 · mutates · licence paid · selection

Writes characters and styledRuns together (FMT-001 §4.6.6). Without –keepRuns the mixed styles are dropped and the text takes the node’s style; with it the runs are kept and cut to the new length. A layer whose name followed its text is renamed. Node-level text properties (font, size, alignment) are set with text.setFont, text.align or node.update. Caret edits in the editor use text.edit.

ud text.set --node "Screens/Login/Title" --characters "Welcome back"

text.edit#

Edit Text. Replace a range of a text node’s characters, keeping and shifting its styled runs (caret edits).

Since 0.2 · mutates · licence paid · selection

The one command the canvas text editor uses for typing, deleting and pasting plain text (TXT-7): [start, end) in UTF-16 offsets is replaced by –insert. Runs after the edit shift; the inserted text takes the style of the character before it. An empty –insert deletes; start = end inserts. The result gives the caret after the insertion.

ud text.edit --node nd-91c0d4e2aa17 --start 7 --end 7 --insert "dear "
ud text.edit --node nd-91c0d4e2aa17 --start 0 --end 5 --insert ""

text.setRange#

Style Text Range. Set font, size, colour, spacing, case, decoration, link or text style on a range of a text node.

Since 0.2 · mutates · licence paid · selection

Mixed styles (TXT-2), as Figma’s setRange… functions: [start, end) in UTF-16 offsets gets the properties of –set; runs are split and merged, and a run property equal to the node’s value is dropped (FMT-001 §4.6.6). A null value resets a property to the node’s value in the range.

ud text.setRange --node "Screens/Login/Title" --start 0 --end 7 --set '{"fontName":{"family":"Inter","style":"Bold"}}'
ud text.setRange --node nd-91c0d4e2aa17 --start 8 --end 12 --set '{"hyperlink":{"type":"URL","value":"https://softforge.dev"},"textDecoration":"UNDERLINE"}'

text.setParagraph#

Set Paragraph Style. Set list, indentation and spacing on whole paragraphs of a text node.

Since 0.2 · mutates · licence paid · selection

Paragraph properties (TXT-3) cover whole paragraphs (FMT-001 §4.6.6): name them by index (–paragraphs, 0 = first), or give a range and every paragraph it touches is styled. listOptions makes bulleted (UNORDERED) or numbered (ORDERED) lists; indentation nests them.

ud text.setParagraph --node nd-91c0d4e2aa17 --paragraphs '[1,2,3]' --set '{"listOptions":{"type":"UNORDERED"}}'
ud text.setParagraph --node nd-91c0d4e2aa17 --start 0 --end 40 --set '{"paragraphSpacing":8}'

text.setFont#

Set Font. Set the font family, style, size, line height and letter spacing of whole text nodes.

Since 0.2 · mutates · licence paid · selection · aliases text.font

The Text section’s font, style and size for whole nodes (CLI-001 §5.1). A new family keeps each run’s style (bold words stay bold); a new style or size replaces the run overrides of that property. Fonts are referred to by name; a font that is not installed renders with the fallback and is listed as missing (TXT-6). –lineHeight takes {unit: “AUTO”} or {unit: “PIXELS” | “PERCENT”, value}, –letterSpacing {unit: “PIXELS” | “PERCENT”, value} (TXT-4); they replace the run overrides of that property too.

ud text.setFont --node nd-91c0d4e2aa17 --family Inter --style "Semi Bold" --size 24
ud text.setFont --query 'text' --family Roboto
ud text.setFont --node nd-91c0d4e2aa17 --lineHeight '{"unit":"PERCENT","value":140}' --letterSpacing '{"unit":"PIXELS","value":-0.2}'

text.align#

Align Text. Set the horizontal and vertical alignment of text nodes.

Since 0.2 · mutates · licence paid · selection

Paragraph alignment (TXT-3): horizontal LEFT, CENTER, RIGHT or JUSTIFIED; vertical TOP, CENTER or BOTTOM within a fixed-height text box.