2. Working with the editor
When a live editor has the file open, ud does not touch the file.
2.1 Through the editor or on the file#
When a live editor has the file open, ud does not touch the file. It sends the command over the local
bridge to that editor (SRS CMD-27), which applies it:
- The change appears at once. The changed nodes flash with the actor’s colour and name (SRS UI-7).
- It goes through the same queue as the user’s own edits, one whole command or script at a time.
- It is one undo step. Ctrl+Z takes it back.
- If the editor had no unsaved changes, it saves after the change so that disk and git keep up.
- Reads see what the editor holds, including what is not saved yet, and the user’s selection.
With no live editor, ud edits the file directly. A lock file (.<name>.design.lock) next to it lets several
commands run at the same time, and the file is replaced atomically.
ud where prints which of the two applies, the resolved file, the actor and the licence state.
--no-live forces direct file access; --live fails when no editor has the file open.
2.2 Which file: fileKey#
Every tool has Figma’s fileKey parameter. ud resolves it in this order (SRS CMD-2):
| Form | Example |
|---|---|
Path to a .design file, absolute or relative to the working folder |
designs/app.design |
| Document id from the file’s tree | doc-7a1e93c04b2f |
ud:// link, as the editor’s “Copy link to selection” gives it |
ud://designs/app.design?node-id=nd-3f9a0c1e7b2d |
| Left out | the file of the only live editor, else UD_FILE, else the only .design file in the folder |
A figma.com URL is refused with code unsupported and the hint ud import figma <url>.
The positional [file] argument and --file are synonyms of --fileKey for native commands.
2.3 Which node: nodeId#
nodeId accepts (SRS CMD-3):
| Form | Example | Note |
|---|---|---|
| Native id | nd-3f9a0c1e7b2d |
The canonical form. |
| Native id with a colon | nd:3f9a0c1e7b2d |
Figma skills turn node-id=1-2 into 1:2; both resolve to the same node. |
| Page id | pg-0b44e1d2a9c3 |
For get_metadata, the page outline. |
| Name path | Home/Header/Logo |
From the page. Ambiguous paths are an error that lists the candidates. |
node-id of a ud:// link |
Native commands also take --query '<selector>' (section 6).
2.4 Who signs#
Every event carries by (SRS CMD-29): --as <name>, else UD_ACTOR, else Claude when CLAUDECODE is set,
else the git user name, else the OS user name. whoami prints the result.
2.5 Licence#
Every read tool is free, including get_design_context, get_screenshot, ud render, exports and
download_assets. Tools and commands that change the document need a paid plan or the trial. A refused change
exits with code 4 and says how to unlock it (SRS LIC-2, LIC-5). use_figma scripts that only read are allowed
on the Free plan: the licence check happens at the first mutation.
The gate exists from 0.1 (review decision D9): the registry asks a licence provider before every mutation and
exit code 4 is wired from the first release. Until 1.0 the provider is a stub that always answers “paid”, so
nothing is refused in practice; 1.0 replaces the stub with the real licence (SRS LIC-1 – LIC-6). ud mcp and
the VS Code language-model tools go through the same gate as ud on the command line: they are not “AI
features” in the sense of LIC-2, which covers the AI panel and quick actions only.