# CLI reference (glassly)

> The glassly command: develop, release, and publish Glassly miniapps.

Source: https://docs.glassly.ai/app-devs/reference/cli/

`@glassly/cli` provides the `glassly` command. Install it globally:

```bash
bun add -g @glassly/cli
glassly --help
```

Every scaffolded project also has its own copy as a dev dependency. Inside a
project, the global `glassly` runs that copy, so each project uses the tooling
version its `package.json` pins. `glassly update` is the exception: it always
runs the global copy, so an old project copy can still be updated.

The CLI is Bun-only: it ships as TypeScript and runs under Bun. Use `bun`
(or `bunx`), not `npx`/Node.

| Command | What it does |
|---|---|
| [`update`](#update) | Updates the project's Glassly SDK and tools and the global `glassly` to the newest release. |
| [`dev`](#dev) | Dev server with hot reload; prints a QR to load the miniapp on a phone. |
| [`sim`](#sim) | Runs the miniapp in the desktop simulator; subcommands send input and read the display. |
| [`release`](#release) | Builds, packs, and serves a QR to install a release on phones over LAN. |
| [`build`](#build) | Builds both layers into `dist/`. |
| [`pack`](#pack) | Validates the manifest and zips `dist/` into `<pkg>-<version>.gls`. |
| [`manifest`](#manifest) | Interactive wizard for editing `miniapp.json`. |
| [`permission`](#permission-and-hardware) | Add / remove / list manifest permissions. |
| [`hardware`](#permission-and-hardware) | Add / remove / list manifest hardware requirements. |
| [`schema print`](#schema) | Prints the canonical `miniapp.json` JSON Schema. |
| [`login`](#login-and-logout) | Signs in to the Developer Console from the terminal. |
| [`org`](#login-and-logout) | Shows or creates your developer org. |
| [`publish`](#publish) | Builds, packs, signs, uploads, and submits a release to the Store. |
| [`miniapps`, `releases`](#miniapps-and-releases) | Inspect your org's packages and releases. |
| [`listing`, `media`](#listing-and-media) | Store listing copy, icon, and screenshots. |
| [`feedback`](#feedback) | Reports a gap, bug, or docs mismatch to the Glassly team. |

Every project command takes `--cwd <path>` to run against a directory other
than the current one.

## `update`

```bash
glassly update                 # project packages + global glassly
glassly update --channel beta  # move to another channel
glassly update --no-global     # project only
```

Rewrites the `@glassly/miniapp`, `@glassly/cli`, and `@glassly/miniapp-cli` pins
in `package.json` to the newest release on a channel (`latest`, `beta`, or
`dev`), sets `sdkVersion` in `miniapp.json` to match, and runs `bun install`.
It leaves `minHostVersion` alone, because raising it hides the miniapp from
older Glassly App versions. The default channel is the one the project's
installed SDK comes from. It then upgrades the global `glassly` with the
package manager that installed it (`bun add -g` or `npm install -g`).

Once a day the CLI checks npm for newer versions of the global CLI and the
project's packages. When something is behind, it prints a one-line notice before
the command runs. Set `GLASSLY_NO_UPDATE_CHECK=1` to turn the check off. It is
already off when `CI` is set.

## `dev`

```bash
glassly dev
glassly dev --no-iroh   # LAN-only QR
```

Validates `miniapp.json`, builds both layers, serves them over your LAN, and
prints a QR (and a `miniapp://dev?...` URL). It also runs a **dev sidecar**
WebSocket on the next port up for live reload and console-log forwarding back to
your terminal (non-fatal if it can't start). It watches for Wi-Fi/LAN-IP changes
every 2 seconds and reprints the QR.

The QR also carries an [iroh](https://www.iroh.computer) ticket, so the phone can
reach your computer from any network, directly or through n0's public relays. The
iroh identity is kept per package in `~/.glassly/dev-tunnel/`, so a saved dev
miniapp reconnects after you restart `dev` without a re-scan. Older Glassly App
builds ignore the ticket and use the LAN URL. `--no-iroh` leaves it out, and on
machines without an iroh binding (Intel Macs) the QR is LAN-only.

If you are signed in with `glassly login`, `dev` also signs a dev identity for
the miniapp so `session.auth` works against your backend during development.
Pass `--auth` to fail instead of falling back when you are signed out.

The starting port comes from `"port"` in `miniapp.json` (default `3000`); if it or
its sidecar neighbor is busy, the CLI scans upward for a free adjacent pair.

`--qr` / `-q` sets the terminal QR size (`small`/`sm`, `medium`/`md`, `large`/`lg`;
defaults to `medium`). `--qr-output <path>` writes the QR as a PNG to that path
instead of a temp file that gets cleaned up on exit.

On the phone, in the Glassly App, open **Settings → Miniapp Developer Settings
→ Scan Miniapp QR Code**. `Ctrl+C` stops everything.

`dev` is live and temporary. Keep the CLI and computer running: 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` for an installed miniapp that works without the
computer.

## `sim`

```bash
glassly sim                  # build, run, and open the simulator window
glassly sim --no-open        # same, without opening a browser
glassly sim --detach         # start in the background; returns once it is ready
glassly sim --port 4600      # start on a port other than 4500
```

Runs the miniapp on your computer with no phone or glasses; see
[Simulator](https://docs.glassly.ai/app-devs/getting-started/simulator.md). It rebuilds and reloads on
save. With `--detach` it prints the address and a log file path, and a
simulator already running for the project is reused.

The subcommands below talk to the simulator running for the current project
(`--cwd <path>` for another project, `--port <port>` for a specific one).

| Command | What it does |
|---|---|
| `sim status [--json]` | Background state, subscriptions, sensors, and any calls that are not simulated. |
| `sim screen [--json]` | The elements on the glasses display, one per line. |
| `sim screenshot [path] [--scale n] [--no-wait]` | The display as a PNG (default `./glassly-sim.png`). Waits for running transitions unless `--no-wait`. |
| `sim tap [--b]`, `double-tap`, `triple-tap`, `hold`, `swipe-up`, `swipe-down` | Touch bar gestures. `tap` is tap A (`index` 0); `--b` sends tap B (`index` 1). |
| `sim look-up`, `sim look-down` | Head position. |
| `sim touch <gesture>` | Any gesture by its wire name, such as `swipe_left` or `dial_up`. |
| `sim button [short\|long]` | A button press. |
| `sim phone <iphone\|duo>` | Show the phone page on an iPhone or a folded iPhone Duo, with that device's safe area and capsule. |
| `sim say <text> [--interim] [--language code]` | Speech, delivered as a transcription. |
| `sim translate <text> [--from code] [--to code]` | A translation result. |
| `sim location <lat> <lng>`, `sim heading <degrees>` | Phone location and compass. |
| `sim battery <level> [--phone] [--charging]` | Glasses (or phone) battery. |
| `sim disconnect`, `sim connect` | Disconnect and reconnect the glasses. The host pauses a miniapp while they are disconnected. |
| `sim notify --title --content [--app]` | A phone notification. |
| `sim event <stream> [json]` | An event on any stream by its wire name. |
| `sim ui send <channel> [json]` | A broadcast from the phone page (`glassly.send`). |
| `sim ui request <channel> [json]` | An RPC call from the phone page (`glassly.request`); prints the result. |
| `sim logs [--since seq] [-f] [--source list] [--json]` | Console output from both layers, build errors, and simulator notes. `--source bridge` shows channel traffic. |
| `sim restart`, `sim stop` | Restart the background script; stop the simulator. |

Screenshots use the [`@napi-rs/canvas`](https://www.npmjs.com/package/@napi-rs/canvas)
binding. On a platform without one, everything else still works and
`sim screen` remains available.

## `release`

```bash
glassly release
glassly release --no-cache   # force rebuild even if the cached zip is fresh
```

The all-in-one path for putting a build on real devices. It validates, builds,
packs, and serves the result behind a QR so you can install on as many phones as you want.

It reuses a cached `build/<pkg>-<version>.gls` when every source file is older
than the zip, otherwise rebuilds (auto-detecting your package manager from the
lockfile). It serves the bundle, manifest, and icon over HTTP on `0.0.0.0` and
prints a `miniapp://release?...` QR, then stays up so multiple devices can
install. Each install logs a line. Installed miniapps run offline and persist
across restarts; no laptop needed after install.

`release` takes the same `--qr` / `-q` and `--qr-output <path>` flags as `dev`.

## `build`

```bash
glassly build
```

Runs the project's production build (`bun run build`, which executes your
`build.ts`) so `dist/background/index.js` and `dist/ui/*` are current. `pack`,
`release`, and `publish` all run this for you.

## `pack`

```bash
glassly pack
glassly pack --no-build   # zip the existing dist/ as-is
```

Produces the distributable artifact only (`release` calls this internally). It
builds with `NODE_ENV=production`, verifies `dist/`, validates the manifest,
copies `miniapp.json` + `icon.png` into `dist/`, and zips to
`build/<pkg>-<version>.gls`. A `.gls` file is a plain zip under the extension
the Glassly App registers as its own, so it opens in the app when shared
(see [Distribution](https://docs.glassly.ai/app-devs/getting-started/distribution.md#share-the-file)).
It is also what `publish` uploads to the Glassly Miniapp Store.

`pack` requires the `zip` binary on `PATH` (preinstalled on macOS and most Linux;
on Windows use WSL). `build/` self-ignores from git.

## `manifest`

```bash
glassly manifest
```

An interactive wizard for `miniapp.json`: edit permissions and hardware
requirements, show the current manifest, or finish. It saves after each confirmed
change, so `Ctrl+C` never loses a saved edit.

## `permission` and `hardware`

Object-verb edits that share the wizard's validation:

```bash
glassly permission list
glassly permission add [TYPE]      # interactive if TYPE omitted
glassly permission remove [TYPE]

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

Permission `TYPE`: `MICROPHONE`, `CAMERA`, `CALENDAR`, `LOCATION`,
`BACKGROUND_LOCATION`, `READ_NOTIFICATIONS`, `POST_NOTIFICATIONS`, `API_KEYS`,
`MEMORY`, `AI`, `SPEAKERS`, `DISPLAY_MIRROR`, `MANAGE_MINIAPPS`,
`PLATFORM_SETTINGS`. Hardware
`TYPE`: `CAMERA`, `DISPLAY`, `MICROPHONE`, `SPEAKER`, `IMU`, `BUTTON`, `LIGHT`,
`WIFI`; `LEVEL`: `REQUIRED`, `OPTIONAL`. See [the manifest](https://docs.glassly.ai/app-devs/core-concepts/miniapp-manifest.md)
for what each means.

## `schema`

```bash
glassly schema print
```

Prints the canonical `miniapp.json` JSON Schema to stdout: useful for CI
validation or IDE config. The same schema ships at
`node_modules/@glassly/miniapp-cli/schema/miniapp.schema.json`, which the `$schema`
line in a scaffolded `miniapp.json` references for editor autocomplete.

## `login` and `logout`

```bash
glassly login            # opens Glassly's sign-in page in a browser
glassly login --no-open  # print the URL and code instead
glassly whoami
glassly logout
```

`login` signs you in to your Glassly developer account with a one-time device
code: approve it on the sign-in page the CLI opens, and the CLI stores a session
for the other Store commands. Your account, org, releases, and API keys are
managed in the [Developer Console](https://console.glassly.ai). The session and the bundle signing key the CLI
registers for you are stored per backend in `~/.glassly/cli/`, readable only by
your user. `whoami` shows the current login; `logout` removes it.

Create your developer org in the console first, or from the terminal with
`glassly org init --name "Your Org" --prefix com.example` (`glassly org show`
prints it). The org owns the package prefix every miniapp you publish must
start with.

### Headless sign-in (CI and AI agents)

Where no one can approve a browser sign-in, use an API key instead of `login`.
An org owner or admin creates one on the
[API keys page](https://console.glassly.ai/tokens) of the Developer Console;
set it as `CLI_TOKEN` and the Store commands use it for that org:

```bash
export CLI_TOKEN=<api key from console.glassly.ai/tokens>
glassly miniapps list
```

## `publish`

```bash
glassly publish
glassly publish --no-build   # pack and upload the existing dist/
glassly publish --no-pack    # upload the existing build/<pkg>-<version>.gls
```

Run from the miniapp folder after `glassly login`. It reserves the package name
for your org if needed, builds and packs, signs the bundle, uploads it with any
`store/` icon and screenshots, and submits the release for review. See
[Distribution](https://docs.glassly.ai/app-devs/getting-started/distribution.md) for what happens next.

## `miniapps` and `releases`

```bash
glassly miniapps list
glassly miniapps create <packageName> --name "Display name"
glassly miniapps delete <packageName>
glassly releases list <packageName>
glassly releases submit <packageName> <releaseId>
```

`publish` creates the package record and submits the release for you; these
are for inspecting state or managing packages by hand.

## `listing` and `media`

```bash
glassly listing set <packageName> --tagline "..." --description "..." --tags a,b
glassly media list <packageName>
glassly media add <packageName> <file.png>                     # a screenshot
glassly media add <packageName> <file.png> --role store_icon   # the icon
glassly media rm <packageName> <assetId>
```

Listing overrides replace the `tagline`, `description`, and `tags` from
`miniapp.json` on the Store card. Media uploads replace or extend the icon and
screenshots that `publish` took from the bundle and the `store/` folder.

## `feedback`

```bash
glassly feedback "No simulator for the R1 ring"
```

Sends a report to the Glassly team with the CLI, SDK, and runtime versions and
the package name from `miniapp.json` attached. No sign-in needed; if you are
signed in, the report carries your account. Prints a `rep_...` report id. See
[Report a gap or bug](https://docs.glassly.ai/app-devs/reference/feedback.md) for the options and the
equivalent HTTP call.
