2. Working with the editor

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.