@elyx-design/cli

中文文档
0.0.1-preview.18273.g1dbfdb598f发布于 2026/11/17SEE LICENSE IN LICENSEES Module近 30 天下载 7402

Command-line tools for Elyx

原始使用文档
文档目录9 节
  1. Install
  2. Open a project
  3. Platform packages
  4. Linux
  5. Windows
  6. Project dependencies
  7. Dependency resolution
  8. Layer targets
  9. Figma import

@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.

版本与发布记录

@elyx-design/cli 共发布 176 个版本,首次发布于 2026/07/15;过去 12 个月发布了 176 个版本。

版本发布日期距今
0.0.1-preview.18273.g1dbfdb598flatest2026/11/17今天
0.0.1-nightly.18264.g9146e24ca1nightly2026/11/17今天
0.0.1-nightly.18188.g5b1039048a2026/11/161 天前
0.0.1-nightly.18172.g09123d2f002026/11/152 天前
0.0.1-nightly.18159.g4b9674390d2026/11/152 天前
0.0.1-nightly.17997.g94b41aee232026/11/134 天前

其他发布通道:bootstrap → 0.0.0-bootstrap.0,preview → 0.0.1-preview.15345.gd9409cf06,nightly → 0.0.1-nightly.18264.g9146e24ca1。

关于 @elyx-design/cli 的常见问题

@elyx-design/cli 是什么?

Command-line tools for Elyx

如何安装 @elyx-design/cli?

在项目目录运行 npm install @elyx-design/cli,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 elyx,可以用 npx elyx 直接运行。

@elyx-design/cli 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/elyx-design__cli 是否存在。

@elyx-design/cli 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@elyx-design/cli 可以商用吗?

@elyx-design/cli 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中,请阅读该文件确认可否商用。以上为概括,不构成法律意见,请以许可原文为准。

@elyx-design/cli 的下载量有多少?

根据 npm 官方下载统计,@elyx-design/cli 在 2026/10/14 – 2026/11/12 这 30 天内被下载 7,402 次,日均约 247 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@elyx-design/cli 还在维护吗?

最新版本 0.0.1-preview.18273.g1dbfdb598f 发布于 2026/11/17(今天);至今共发布 176 个版本,其中过去 12 个月发布了 176 个;首次发布于 2026/07/15。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。