@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
| Command | What it does |
|---|---|
dev | Starts the dev server with hot reload, prints a QR to load it on a phone |
sim | Runs the miniapp in the desktop simulator; subcommands drive it |
release | Builds, packs, and serves a QR to install the release on a phone over LAN |
pack | Validates the manifest and zips dist/ into <pkg>-<version>.zip |
manifest | Interactive top-level wizard for editing miniapp.json |
permission list | add | remove | Object-verb manifest edits for permissions |
hardware list | add | remove | Object-verb manifest edits for hardware requirements |
schema print | Prints 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:
- Reads + validates
miniapp.json(hard-fails on bad permissions / hardware types so you don't have to debug it on the phone). - Runs the project's
build.tssodist/background/index.jsanddist/ui/*are current. - Picks the first free adjacent port pair starting at
port: one for static files and the next for the dev sidecar. - Starts a static server that serves
miniapp.json,icon.png, and project files. - 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. - Binds an iroh endpoint (key kept per package in
~/.glassly/dev-tunnel/) that forwards authenticated phone streams to both servers. Skipped with--no-irohor where@number0/irohhas no binding (Intel Macs). - 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 ignoreiroh/tokenand useurl. - 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:
- Validates
miniapp.jsonand runs the project'sbuild.ts. - Evaluates
dist/background/index.jsin a Bun worker that provides the__dispatchbridge the SDK'sDispatchTransportexpects. Node and Bun globals the phone's JS context lacks (process,Buffer,require,performance, ...) are hidden from the bundle. - Answers the bundle's requests from
SimHost(src/sim/host.ts), which mirrors the Glassly App's runtime for the calls it covers and repliesNOT_IMPLEMENTEDfor the rest. Scenes go through the SDK's ownprocessScene/diffScene(@glassly/miniapp/display), the code the app runs, against the app's Simulated Glasses profile. - Serves the simulator window, the miniapp's UI page at
/ui/(with thewindow.Glasslyglobals andwindow.glasslyshim from@glassly/miniapp/host, carried over a WebSocket), and a JSON control API under/api/, all on127.0.0.1(default port4500). - 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:
- Validates
miniapp.json. - Build cache. Looks for
build/<packageName>-<version>.zip. If it exists and every project source file (excludingnode_modules,dist,build,.git) is older than the zip, reuses it. Otherwise rebuilds. - Build. Detects your package manager (
bun.lock→bun,pnpm-lock.yaml→pnpm,yarn.lock→yarn, elsenpm) and runs<pm> run build. Yourpackage.jsonmust define abuildscript that producesdist/. - Pack. Calls the same logic as
glassly pack: validates the manifest, copiesminiapp.json+icon.pngintodist/, zips tobuild/<packageName>-<version>.zip. Prints size + duration. - Serve. Picks a free port between 6789 and 6798. Hosts the bundle, manifest, and icon over HTTP on
0.0.0.0:GET /miniapp.jsonGET /icon.pngGET /bundle.zipGET /__host_release/health
- Prints a
miniapp://release?url=<lan-base>&package=…&version=…&name=…URL + QR. - Stays up so multiple devices can install. Each
/bundle.zipfetch 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":
installcollides with package managers (bun run installis reserved). Naming the action after the artifact you're producing avoids that collision and matches Android'sinstallReleasemental 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:
- Runs
<pm> run buildwithNODE_ENV=production(same asrelease), so the zip always contains a production bundle, never a stale dev build left behind bydev. Pass--no-buildto skip this and zip whatever is already indist/. - Verifies
dist/exists. - Validates
miniapp.json. - Copies
miniapp.jsonandicon.pngintodist/. - Runs the system
zip -rcommand to producebuild/<packageName>-<version>.zipand 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
zipbinary onPATH(preinstalled on macOS and most Linux distros). On Windows, installzipvia 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
EXISThardware 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 regenerateexists too but is package-internal: it rewrites the published schema file from the in-source allowed-values lists (bun run buildhere 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.
| Field | What it does |
|---|---|
entry | Two-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). |
alwaysOn | Boolean, 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. |
sdkVersion | Semver of the @glassly/miniapp SDK this bundle targets. |
minHostVersion | Lowest 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. |
actions | Actions 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. |
sdkVersionandminHostVersionare validated against the schema. Only the Store enforcesminHostVersion; the runtime does not check either at launch (the host'scheckManifestVersionsgate 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.tscommand,host.tsprotocol,server.tswindow + control API,background.tsworker,screenshot.ts,client/window page) - QR rendering:
src/qr.ts - Generated JSON Schema:
schema/miniapp.schema.json(regenerated viaschema regenerate)