@elyx-design/cli
Command-line tools for Elyx projects, documents, and cloud services.
Install
npm install --global @elyx-design/cli
elyx --help
Open a project
Open the current directory or another project folder in the matching installed Elyx app release:
elyx .
elyx /path/to/project
Opening a project requires the Elyx desktop app. Local document commands do not
require signing in. Run elyx --help to list commands, and
elyx <command> --help for a command's options.
Platform packages
@elyx-design/cli provides the JavaScript launcher and the bundled props
analyzer. npm installs a matching optional package for your operating system and
CPU architecture, named @elyx-design/cli-<platform>-<architecture>. That
package supplies the native elyx executable; the launcher forwards your
arguments and exit status to it.
Keep optional dependencies enabled when installing. If the launcher reports a missing platform package, reinstall with optional dependencies included:
npm install --global --include=optional @elyx-design/cli
Linux
Linux supports x86-64 and arm64 (aarch64) systems using glibc. Ubuntu 24.04 is the tested environment, and Fontconfig and libcurl must be installed. The executable embeds libc++, so the system's libc++ version does not matter. Alpine and other musl-based distributions are not currently supported.
Windows
Windows supports x64 systems. Its platform package keeps Skia's ICU data,
icudtl.dat, beside elyx.exe for text layout. Keep these files together.
Project dependencies
Declare copied dependencies in a project's elyx.json. Relative paths without a
scheme still refer to editable workspace members.
{
"dependencies": {
"theme": "path:../theme",
"icons": "git+https://example.com/design/icons#^1.0.0",
"tokens": "git+ssh://[email protected]/design/tokens#main",
"components": {
"git": {
"url": "[email protected]:design/components.git",
"ref": "~2.1.0"
},
"override": true
},
"brand": { "path": "../brand" }
}
}
The key is the import name: icons imports as @icons/colors.elyx. Git
dependencies use git+<url>#<ref> or {"git": {"url", "ref"}}, where url may
keep the git+ prefix. Bare git://host/repo#ref also works and uses Git's
native transport. A ref starting with ^, ~, or = is a semver range;
anything else names a tag, branch, or full commit, and no ref means HEAD. Path
dependencies use path:<path> or {"path": "<path>"}, relative to the
declaring project or absolute.
A Git package is identified by its URL's lowercase host and path, without
scheme, user, port, or .git, so https://example.com/design/icons.git and
[email protected]:design/icons are one package. Git URLs must be remote; declare
a local checkout with path:. The fetched projects choose each package's URL,
otherwise the first one seen wins; fetches verify commit IDs, so the URL never
changes the snapshot. Git runs with the user's credentials and SSH
configuration, with literal arguments and no shell.
"override": true makes a Git declaration the only requirement on its package,
replacing (and logging) every other declaration of it. Only the fetched projects
can override, and their overrides of one package must agree.
elyx deps fetch
elyx deps update
elyx --workspace /path/to/project deps fetch
Commands use normal project discovery from the current folder or --workspace.
A workspace resolves its members together and keeps elyx.lock and elyx_deps/
beside its workspace manifest. fetch keeps the commits pinned in elyx.lock
and resolves only new dependencies; update resolves every Git dependency
again. Both refresh path copies. Git is only needed for Git dependencies.
Resolution is transitive and backtracks across conflicts. git ls-remote lists
HEAD and tags without downloading objects; branches are looked up on demand,
so the lock records only the branches declarations name. Versions come from tags
spelled exactly v<major>.<minor>.<patch>; =1.2.0 matches tag v1.2.0. A
name that exists as a tag is the tag, otherwise a branch; refs/heads/name
always names the branch. Candidate commits are fetched alone
(--depth=1 --no-tags) into a detached worktree, so servers must allow fetching
commits by ID. Repositories need a project elyx.json at their root; candidates
whose manifest is missing or invalid are skipped. Git packages may use relative
path dependencies within their own commit. Workspace-manifest repositories and
submodules are not supported yet.
Installs go into stable elyx_deps/ folders named by a SHA-256 of the
lock-relative source path (path-), the Git identity and commit (git-), or
both plus the in-repository path (git-path-). elyx.lock records dependency
edges, sources, folders, pinned commits, and each commit's refs and versions, so
declarations can be checked without contacting the remote. Local paths in it are
lock-relative. Commit elyx.lock and ignore elyx_deps/; new projects exclude
and ignore it by default. Installs are staged and backed up, so a failure leaves
the previous lock and copies in place, and the lock is written atomically. An
elyx_deps/.busy folder blocks concurrent commands; after a crash, remove it
once no command is running.
Copies follow the project's indexing rules (files.exclude, asset and font
includes, nested-project boundaries), always keep the root elyx.json, omit
.git, elyx_deps, and elyx.lock, and are read-only. Loading a project
indexes its installed dependencies, transitively, as read-only projects through
elyx.lock; a missing or stale lock or copy produces a diagnostic pointing to
elyx deps fetch or elyx deps update. Projects without external dependencies
need no lock.
Progress is printed as work starts, without colors:
* Resolving github.com/acme/icons
* Getting github.com/acme/icons v1.4.0 (a1b2c3d4e5f6)
* Skipping github.com/acme/icons v1.5.0 (0f1e2d3c4b5a): No elyx.json in the repository root
* Overriding github.com/acme/tokens ^1.0 from github.com/acme/icons v1.4.0 (a1b2c3d4e5f6) with main
* Copying theme (path: ../theme)
Getting names the version or ref that matched; locked fetches skip discovery.
Dependency resolution
Dependency version ranges follow a subset of
npm's semver syntax:
=1.2.3 is exact, ~1.2.3 stays below 1.3.0, and ^1.2.3 below 2.0.0.
Caret keeps the first nonzero component: ^0.2.3 stays below 0.3.0 and
^0.0.3 below 0.0.4. Both accept two components: ~1.2 < 1.3.0, ^1.2 <
2.0.0, ^0.0 < 0.1.0. Only stable versions with up to 14 digits per
component are supported; prereleases, build metadata, other operators, compound
ranges, and Elixir's ~> and == are rejected.
Layer targets
elyx render follows the input file's file {draw-connections: .true} setting
when drawing connection arrows. When rendering a layer with --ref, only
connections contained within that layer appear. Pass --no-connections to omit
arrows from the PNG without changing the file.
elyx find locates layers by exact reference (--ref), the topmost layer at a
board-space point (--at X,Y), or the layers within a rectangle
(--in X,Y,W,H), and returns their geometry in a results array. elyx tree
returns the resolved layer tree of one layer (--ref) or, without one, of the
file's board. Both echo their inputs: find under query, and tree as ref
and depth ("shallow", "full", or an instance budget).
Pass each point or rectangle as one comma-separated argument, such as
--at "420,180" or --in "0,0,800,600". Quotes are optional for these values.
elyx find requires this form and rejects coordinates supplied as separate
numeric arguments. Negative coordinates work with --at=-10,20 or
--at "-10,20".
Each find result and tree node carries a target containing filePath,
sourceRef, and overridePath; a null target means the runtime layer has no
reusable source address. Other fields such as symbol, ref, and path
describe the layer, rather than identifying an exact instance occurrence.
Tree nodes also carry the layer's doc note and its meta map, or null when
absent. meta values keep their Elyx kind (string, number, or boolean), and
instances report the meta they inherit from their source.
A value bound to a design token is written as
{"value": …, "token": "<file>#<group>.<member>"} instead of the plain value.
The token names the context-free declaration, so it stays the same under every
--context, while value is resolved under the selection the tree reports as
contexts. Sizes and constraints are "auto" for hugging content, numbers for
fixed values, "N%" for relative values, and null when unset.
Use the target's file path as the CLI input, sourceRef as --ref, and
overridePath as --override-path. For example:
elyx tree screen.elyx --ref=musicPlayer.track.save
elyx find screen.elyx --ref=card
elyx render screen.elyx --ref=card -o card.png
For descendants, copy sourceRef and overridePath from a target returned by
find or tree without interpreting them. Ambiguous source references fail instead
of choosing an instance. In MCP, pass the returned object as select.target to
elyx_find, root.target to elyx_tree, target to render, or an entry in
focus's targets array. Point and rectangle finds and whole-file trees use
filePath. To render a whole document, pass
target: {filePath: "screen.elyx"}.
elyx css writes a stylesheet for one layer (--ref) or the board: one class
per rendered layer, named after it and made unique. Each rule starts with the
layer's own styles: size, layout, fills, borders, shadows, and typography. Then
come the parts that follow from the tree. Stack items match Yoga, so they don't
shrink, and 100% sizes fill the stack. Layers outside a stack are absolutely
positioned from their authored edges. Clipping frames hide overflow.
display: .none layers are left out. The root keeps no position, so it can be
placed anywhere.
Token values are var(--<prefix>-<scope>-<token>, <value>), named like the
vite-plugin-elyx token stylesheet; pass that stylesheet's prefix as --prefix
(default elyx). Image fills load from paths relative to the working directory.
--format json returns the stylesheet as css plus a rules array; each rule
has its className, ordered declarations, and the layer target.
elyx css screen.elyx --ref=card --prefix=ms
Figma import
For elyx fig inspect, elyx fig convert, and the supported Figma features,
see
the Figma support matrix.