5. Native commands

5.1 Registry commands#

Every registry command is a ud command (SRS CMD-19):

text

ud run <command-id> [file] [--param value …] [--json '<params>']
ud <command-id> …                          # same, when the id does not clash with a tool or helper

ud node.align --query 'frame[name="Login"] > *' --align left
ud layout.set --node "Login/Form" --mode vertical --gap 16 --padding 24
ud text.setFont --node nd-91c0d4e2aa17 --family Inter --style "Semi Bold" --size 24
ud variable.create --collection Colors --name color/brand --type COLOR --value '#4F46E5'

Categories: document, page, node, selection, view, shape, vector, text, fill, stroke, effect, layout, constraint, component, instance, style, variable, library, prototype, dev, comment, version, export, import, codegen, lint. ud commands lists them all and ud help <command> explains one. The command reference on the documentation site is generated from the registry.

5.2 Discovering#

Command	Prints
`ud commands [--category c] [--json]`	All registry commands and tools, with summaries, `since`, `deprecated` and the `writesFiles` and `network` flags (section 8).
`ud help [command \| tool]`	Usage, parameters with defaults, examples, Plugin API equivalent, related commands.
`ud schema <command \| tool>`	Parameter and result JSON Schemas.
`ud plugin-api [--json]`	The coverage table of section 4.2.
`ud where`	File, live or direct, actor, licence.

5.3 Reading#

Command	Does
`ud tree [file] [--node n \| --query q] [--depth n] [--fields f,…]`	Compact indented layer tree: type, name, id, size, layout summary (SRS CMD-33).
`ud inspect <target> [--yaml \| --json] [--fields …]`	One node fully: props, resolved styles and variables, overrides, computed layout.
`ud selection`	The live editor’s selection.
`ud system [--json]`	Design-system digest: variables by collection with modes, styles, components with properties and descriptions, scales (SRS AI-3).
`ud find --query q`	Ids and paths of matching nodes.
`ud versions`, `ud history [--since seq]`	Named versions; event history.
`ud comments [--open]`	Comment threads.

ud tree output:

text

page Screens (pg-0b44e1d2a9c3)
└ frame Login 390×844 col gap16 pad24 (nd-3f9a0c1e7b2d)
  ├ text Title "Welcome back" Inter/SemiBold/28 (nd-91c0d4e2aa17)
  ├ instance Input ◇Input[State=Default] fill×hug (nd-a1b2c3d4e5f6)
  └ instance Button ◇Button[Variant=Primary] fill×48 (nd-c2e8a1f0937b)

5.4 Seeing#

Command	Does
`ud render <target> [--out f] [--format png\|jpg\|webp\|svg\|pdf] [--scale s] [--mode Theme=Dark] [--variant …] [--after 'click:nd-…'] [--region x,y,w,h]`	Image of a node, page or region (SRS CMD-32).
`ud diff <a> <b> [--image out.png]`	Structural and visual diff between seqs, versions, git revisions or files (SRS CMD-35).
`ud lint [target] [--rules file] [--json]`	Findings; exit 1 on errors (SRS CMD-36).
`ud watch [--json]`	Live events as JSON lines (SRS CMD-37).

5.5 Changing#

Command	Does
`ud apply <file.json \| ->`	A transaction of `{ command, params, ref? }` items (SRS CMD-28).
`ud insert --udx <file \| -> [--parent target] [--index i]`	Builds nodes from UDX.
`ud replace <target> --udx <file \| ->`	Replaces a subtree, keeping ids where `id` attributes match.
`ud select <target>`	Sets the live editor’s selection (SRS CMD-26).
`ud new <file> [--template t]`	Creates a file (as `create_new_file`).
`ud import figma <url> \| html <url> \| svg <file> \| image <file>`	Imports (SRS EXP-4 – EXP-6).
`ud export <target> --format png\|svg\|pdf\|udx\|tokens [--out]`	Exports; `tokens` writes DTCG JSON, CSS or TS (SRS VAR-9).
`ud codegen <target> --framework react\|… --out dir`	Generates code into the workspace (SRS DEV-3).
`ud version save "<title>"`	Saves a named version.
`ud consolidate`, `ud validate [--recover]`, `ud upgrade`	File maintenance (FMT-001 §7, §9, §10). `--recover` writes the repairs of tolerant reading as grouped events; run `ud validate` after a git merge.
`ud assets gc [--delete]`	Lists asset files no node refers to; `--delete` removes them (FMT-001 §8).
`ud versions show <vs-…>`	Prints a named version, read from git history when it is older than the WAL base (FMT-001 §10, SRS COL-2).

ud apply example, where $1 refers to the first item’s created node:

json

[
  { "command": "node.create", "params": { "type": "FRAME", "name": "Toast", "parent": "nd-3f9a0c1e7b2d" } },
  { "command": "layout.set",  "params": { "node": "$1", "mode": "horizontal", "gap": 8, "padding": 12 } },
  { "command": "node.create", "params": { "type": "TEXT", "parent": "$1", "characters": "Saved" } }
]

5.6 Common options#

Option	Effect
`--fileKey`, `--file`, positional `[file]`	The file (section 2.2).
`--as <name>`	Actor.
`--json`	Machine-readable output (the MCP `content` array for tools).
`--dry-run`	Validate and print the events without writing (SRS CMD-30).
`--if-version <hash>`	Refuse with exit 3 if the document’s tree hash (FMT-001 §6.9, `sha256:…`) differs; `ud where --json` and every mutation result print the current hash.
`--live` / `--no-live`	Require / avoid the live editor.
`--quiet`	Print only ids or paths.