@glassly/miniapp-cli

中文文档
0.1.14发布于 2026/11/16ES Module近 30 天下载 5514

Build tooling for Glassly miniapps: dev server, packer, manifest validation, and JSON Schema. The glassly command that drives it ships in @glassly/cli.

原始使用文档
文档目录11 节
  1. Commands at a glance
  2. dev
  3. sim
  4. release
  5. pack
  6. manifest
  7. permission
  8. hardware
  9. schema
  10. miniapp.json shape
  11. File map

@glassly/miniapp-cli

Build tooling for Glassly miniapps: the dev server, the packer, manifest validation, and the miniapp.json JSON Schema. Pairs with @glassly/miniapp.

This package has no binary of its own. The glassly command from @glassly/cli wraps every function here as a subcommand, which is what the rest of this document describes:

glassly <command>

Projects also import it directly: build.ts uses @glassly/miniapp-cli/build-helpers, and miniapp.json points its $schema at node_modules/@glassly/miniapp-cli/schema/miniapp.schema.json. That is why it stays a dev dependency next to @glassly/cli.

Commands at a glance

CommandWhat it does
devStarts the dev server with hot reload, prints a QR to load it on a phone
simRuns the miniapp in the desktop simulator; subcommands drive it
releaseBuilds, packs, and serves a QR to install the release on a phone over LAN
packValidates the manifest and zips dist/ into <pkg>-<version>.zip
manifestInteractive top-level wizard for editing miniapp.json
permission list | add | removeObject-verb manifest edits for permissions
hardware list | add | removeObject-verb manifest edits for hardware requirements
schema printPrints the canonical miniapp.json JSON Schema to stdout

Run glassly --help to print the same list.

dev

glassly dev
glassly dev --qr lg              # QR size: sm | md | lg (default md); -q also works
glassly dev --qr-output ./qr.png # also write the QR as a PNG, kept after exit
glassly dev --no-iroh            # LAN-only QR

What it does:

  1. Reads + validates miniapp.json (hard-fails on bad permissions / hardware types so you don't have to debug it on the phone).
  2. Runs the project's build.ts so dist/background/index.js and dist/ui/* are current.
  3. Picks the first free adjacent port pair starting at port: one for static files and the next for the dev sidecar.
  4. Starts a static server that serves miniapp.json, icon.png, and project files.
  5. Starts a dev sidecar on port + 1, a WebSocket the phone connects to for live reload + console-log forwarding back to your terminal. Failure here is non-fatal; the miniapp still runs without live reload.
  6. Binds an iroh endpoint (key kept per package in ~/.glassly/dev-tunnel/) that forwards authenticated phone streams to both servers. Skipped with --no-iroh or where @number0/iroh has no binding (Intel Macs).
  7. Detects the LAN IP, builds a miniapp://dev?url=…&name=…&package=…&dev=<sidecarPort>&iroh=<ticket>&token=… URL, and prints a terminal QR + the raw URL. Older Glassly App builds ignore iroh/token and use url.
  8. Watches for LAN-IP changes (Wi-Fi switch) every 2s and reprints the QR.

Default port is 3000; override the starting point with a "port": <n> field in miniapp.json. If that port or its sidecar neighbor is busy, dev scans upward until it finds a free adjacent pair.

On the phone, open the Glassly App → Settings → Miniapp Developer Settings → Scan Miniapp QR Code. That settings row only appears with debug mode on. With the iroh ticket the phone can be on any network; older Glassly App builds need the same Wi-Fi.

Both dev and release take the same QR flags. --qr / -q sizes the terminal QR (small|medium|large, or sm|md|lg; default medium). --qr-output <path> also writes a PNG. Without it the CLI still writes a PNG to a temp path and deletes it on exit; pass --qr-output when you want to keep the file.

dev is live and temporary. Keep the CLI and computer running because the Glassly App loads the runtime bundle from that LAN server. Dev miniapps are keyed by their manifest package name, so you can scan and test several side by side; rescanning the same package updates only that entry. The Glassly App caches each entry's name and icon. Use bun run release when you need an installed miniapp that works without the computer.

Ctrl+C stops the server, the sidecar, and the IP watcher.

sim

glassly sim                 # build, run, open the simulator window
glassly sim --no-open       # same, without a browser
glassly sim --detach        # start in the background, return once it answers

Runs a miniapp with no phone and no glasses:

  1. Validates miniapp.json and runs the project's build.ts.
  2. Evaluates dist/background/index.js in a Bun worker that provides the __dispatch bridge the SDK's DispatchTransport expects. Node and Bun globals the phone's JS context lacks (process, Buffer, require, performance, ...) are hidden from the bundle.
  3. Answers the bundle's requests from SimHost (src/sim/host.ts), which mirrors the Glassly App's runtime for the calls it covers and replies NOT_IMPLEMENTED for the rest. Scenes go through the SDK's own processScene / diffScene (@glassly/miniapp/display), the code the app runs, against the app's Simulated Glasses profile.
  4. Serves the simulator window, the miniapp's UI page at /ui/ (with the window.Glassly globals and window.glassly shim from @glassly/miniapp/host, carried over a WebSocket), and a JSON control API under /api/, all on 127.0.0.1 (default port 4500).
  5. Watches the project: a change under src/ui/ reloads the page, anything else restarts the background too.

Every glassly sim <subcommand> (screen, screenshot, tap, say, logs, ui request, ...) is a call to that control API on the simulator running for the current project, found through a record in the OS temp directory. screenshot draws the display off screen with MirrorCanvasRenderer on @napi-rs/canvas, the same renderer the window uses.

The simulator needs an @glassly/miniapp that exports @glassly/miniapp/host; on an older SDK it says so and exits.

What it covers, and what it does not, is listed in the public docs: https://docs.glasslyos.com/app-devs/getting-started/simulator.

release

glassly release
glassly release --no-cache        # force rebuild even if cache is fresh
glassly release --qr lg           # QR size: sm | md | lg (default md); -q also works
glassly release --qr-output ./qr.png

The all-in-one verb: build a release, pack it, and serve it behind a QR so you can install on as many phones as you like.

Flow:

  1. Validates miniapp.json.
  2. Build cache. Looks for build/<packageName>-<version>.zip. If it exists and every project source file (excluding node_modules, dist, build, .git) is older than the zip, reuses it. Otherwise rebuilds.
  3. Build. Detects your package manager (bun.lock → bun, pnpm-lock.yaml → pnpm, yarn.lock → yarn, else npm) and runs <pm> run build. Your package.json must define a build script that produces dist/.
  4. Pack. Calls the same logic as glassly pack: validates the manifest, copies miniapp.json + icon.png into dist/, zips to build/<packageName>-<version>.zip. Prints size + duration.
  5. Serve. Picks a free port between 6789 and 6798. Hosts the bundle, manifest, and icon over HTTP on 0.0.0.0:
    • GET /miniapp.json
    • GET /icon.png
    • GET /bundle.zip
    • GET /__host_release/health
  6. Prints a miniapp://release?url=<lan-base>&package=…&version=…&name=… URL + QR.
  7. Stays up so multiple devices can install. Each /bundle.zip fetch logs ✓ Install #N: <name>@<version> → <remote>.

Ctrl+C to stop the server.

On the phone, the Glassly App's QR scanner branches on miniapp://release and uses the dev composer to download + install the bundle. The miniapp lands in lmas/<package>/<version>/ and behaves like any installed local miniapp: it runs offline, persists across restarts, and needs no laptop after install.

Why "release" and not "install": install collides with package managers (bun run install is reserved). Naming the action after the artifact you're producing avoids that collision and matches Android's installRelease mental model.

pack

glassly pack
glassly pack --no-build    # zip dist/ as-is, skip the build

Produces a distributable ZIP. Use this when you want the artifact only; release calls pack internally.

Steps:

  1. Runs <pm> run build with NODE_ENV=production (same as release), so the zip always contains a production bundle, never a stale dev build left behind by dev. Pass --no-build to skip this and zip whatever is already in dist/.
  2. Verifies dist/ exists.
  3. Validates miniapp.json.
  4. Copies miniapp.json and icon.png into dist/.
  5. Runs the system zip -r command to produce build/<packageName>-<version>.zip and prints the absolute path.

build/ is self-ignoring: the CLI writes a .gitignore containing * into it on creation, so packed zips stay out of version control in any repo without touching the project's own .gitignore.

The resulting ZIP is the artifact you'd upload to the miniapp store.

Requires the zip binary on PATH (preinstalled on macOS and most Linux distros). On Windows, install zip via WSL or use a Unix-like shell.

manifest

glassly manifest

Interactive top-level wizard for miniapp.json (Clack-based). Loop:

  • Edit permissions: add, remove
  • Edit hardware requirements: add, remove
  • Show current manifest: pretty-prints the JSON
  • Done: exits

Persists after every confirmed change, so Ctrl+C never loses a saved edit.

The wizard shares its mutation backend (manifest-mutate.ts) with the object-verb commands below; behavior and validation are identical.

permission

glassly permission list
glassly permission add [TYPE]
glassly permission remove [TYPE]

add / remove are interactive when called without TYPE (Clack select prompts) and non-interactive when TYPE is provided.

Allowed TYPE values: MICROPHONE, CAMERA, CALENDAR, LOCATION, BACKGROUND_LOCATION, READ_NOTIFICATIONS, POST_NOTIFICATIONS, API_KEYS, MEMORY, AI, SPEAKERS, DISPLAY_MIRROR, MANAGE_MINIAPPS, PLATFORM_SETTINGS.

Adding a permission interactively prompts for an optional human-readable description (shown in the OS prompt when the user is asked to grant the permission). The Glassly App asks for every declared permission when the miniapp launches: required ones first (declining keeps it closed), then optional ones ("required": false) in one skippable alert.

hardware

glassly hardware list
glassly hardware add [TYPE] [LEVEL]
glassly hardware remove [TYPE]

Allowed TYPE values: CAMERA, DISPLAY, MICROPHONE, SPEAKER, IMU, BUTTON, LIGHT, WIFI. Allowed LEVEL values: REQUIRED, OPTIONAL.

  • REQUIRED: glasses without this hardware can't run the app (hidden in the store / launcher on incompatible devices).
  • OPTIONAL: glasses without this hardware still run the app, in a degraded state.

Add is interactive when called without TYPE / LEVEL. Non-interactive form requires both.

The EXIST hardware type is injected by the phone at runtime (every miniapp implicitly requires that glasses are present). It's intentionally not in the allowed-types list, so don't declare it.

schema

glassly schema print

Prints the canonical miniapp.json JSON Schema to stdout. Useful for piping into IDE config or for validation in CI.

The schema is generated from the same constants the validator uses (ALLOWED_PERMISSIONS, ALLOWED_HARDWARE_TYPES, ALLOWED_HARDWARE_LEVELS), so it can never drift from validation behavior.

The published schema file ships at node_modules/@glassly/miniapp-cli/schema/miniapp.schema.json for editors that read $schema from miniapp.json. The scaffolder (@glassly/create-miniapp) injects this $schema line into new projects automatically.

glassly schema regenerate exists too but is package-internal: it rewrites the published schema file from the in-source allowed-values lists (bun run build here does the same). Authors don't need it.

miniapp.json shape

{
  "$schema": "./node_modules/@glassly/miniapp-cli/schema/miniapp.schema.json",
  "packageName": "com.glassly.example",
  "version": "1.0.0",
  "name": "Glassly Example",
  "description": "…",
  "icon": "icon.png",
  "port": 3000,
  "type": "standard",
  "sdkVersion": "0.3.0",
  "minHostVersion": "0.3.0",
  "entry": {
    "background": "background/index.js",
    "ui": "ui/index.html"
  },
  "permissions": [{"type": "MICROPHONE", "description": "Listen for what to caption."}],
  "hardwareRequirements": [
    {"type": "DISPLAY", "level": "REQUIRED"},
    {"type": "MICROPHONE", "level": "REQUIRED"}
  ],
  "actions": [
    {
      "id": "start_caption",
      "description": "Start live captions on the glasses. Use when the user asks to caption a conversation.",
      "visibility": "public",
      "parameters": {"type": "object", "properties": {"language": {"type": "string"}}}
    }
  ]
}

Required: packageName, version, name, hardwareRequirements. Everything else is optional.

FieldWhat it does
entryTwo-layer bundle entry points. background (required if present) is the always-running JSContext entry, e.g. background/index.js; ui is the on-demand WebView entry HTML. Pure-background miniapps omit ui.
type"standard" (default, ships a UI WebView), "background" (JSContext only), or "dashboard" (can hold the dashboard role: one dashboard runs at a time and gets the display overlay slot; grants no privileges by itself).
alwaysOnBoolean, default false. Start at host launch and keep the background running when its switcher card is dismissed. The wearer can override this default and explicitly stop the miniapp.
sdkVersionSemver of the @glassly/miniapp SDK this bundle targets.
minHostVersionLowest Glassly App version that can run this bundle; the app reports its release family version (0.3.0 today). The Glassly Miniapp Store won't install or update a release whose minHostVersion is above the running Glassly App, and says so on its card and page.
actionsActions other miniapps can discover and invoke via session.actions, mapping 1:1 onto MCP tools. Each needs id (lowercase, ^[a-z][a-z0-9_]*$, ≤64 chars) and an AI-facing description; visibility is "public" (default) or "system" (system miniapps such as the AI assistant only), and parameters is a JSON Schema for the input.

sdkVersion and minHostVersion are validated against the schema. Only the Store enforces minHostVersion; the runtime does not check either at launch (the host's checkManifestVersions gate exists and is never called).

packageName must be reverse-DNS (^[a-zA-Z][a-zA-Z0-9_]*(\.[a-zA-Z][a-zA-Z0-9_]*)+$).

port defaults to 3000 for dev and is ignored by release (which picks its own free port). For dev, this is the starting port; if the port or its sidecar neighbor is busy, the CLI scans upward until it finds a free adjacent pair.

The allowed-value lists are read from the project's installed @glassly/miniapp (@glassly/miniapp/manifest), a peer dependency, so the validator, the schema, and the host agree by construction. A project whose SDK predates that export gets a clear upgrade message.

File map

  • Command implementations (exported from src/api.ts, wired to subcommands by @glassly/cli): src/{dev,release,pack,permission,hardware,schema,manifest-wizard}.ts
  • Manifest validation: src/manifest.ts; allowed values loaded from the SDK: src/manifest-vocabulary.ts
  • Manifest mutation backend (shared by wizard + object-verb commands): src/manifest-mutate.ts
  • Manifest read/write helpers: src/manifest-format.ts
  • Permission/hardware human-readable hints: src/permission-hints.ts
  • Dev sidecar WebSocket server: src/dev-server.ts
  • Simulator: src/sim/ (sim.ts command, host.ts protocol, server.ts window + control API, background.ts worker, screenshot.ts, client/ window page)
  • QR rendering: src/qr.ts
  • Generated JSON Schema: schema/miniapp.schema.json (regenerated via schema regenerate)

版本与发布记录

@glassly/miniapp-cli 共发布 49 个版本,首次发布于 2026/08/24;过去 12 个月发布了 49 个版本。

版本发布日期距今
0.1.14latest2026/11/16今天
0.1.14-beta.0beta2026/11/16今天
0.1.14-dev.0dev2026/11/16今天
0.1.132026/11/16今天
0.1.13-beta.02026/11/16今天
0.1.13-dev.02026/11/16今天

关于 @glassly/miniapp-cli 的常见问题

@glassly/miniapp-cli 是什么?

Build tooling for Glassly miniapps: dev server, packer, manifest validation, and JSON Schema. The glassly command that drives it ships in @glassly/cli.

如何安装 @glassly/miniapp-cli?

在项目目录运行 npm install @glassly/miniapp-cli,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:@glassly/miniapp(>=0.3.1-dev.528 <0.5.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@glassly/miniapp-cli 支持 TypeScript 吗?

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

@glassly/miniapp-cli 支持 ESM 还是 CommonJS?

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

@glassly/miniapp-cli 可以商用吗?

@glassly/miniapp-cli 使用 未声明 许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利,商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括,不构成法律意见,请以许可原文为准。

@glassly/miniapp-cli 的下载量有多少?

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

@glassly/miniapp-cli 还在维护吗?

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