# Simulator

> Run a miniapp on your computer with no phone and no glasses, and drive it from the terminal.

Source: https://docs.glassly.ai/app-devs/getting-started/simulator/

`glassly sim` runs your miniapp on macOS, Linux, or Windows. The background
script runs in a worker, the glasses display is drawn in a browser window, and
the phone page loads in a phone frame beside it. Every input the glasses and
phone would produce can be sent from that window or from the command line, so a
script or a coding agent can change code, act, and check the result without a
person in the loop.

```bash
glassly sim
```

It validates `miniapp.json`, builds both layers, opens the simulator window, and
rebuilds and reloads when you save a source file. Console output from both
layers prints in the terminal and in the window's log.

## The window

- **Glasses**: the display, drawn by the same scene pipeline the Glassly App
  runs (clamping, element budgets, text wrapping, transitions). It simulates
  the app's Simulated Glasses, a 576×288 canvas with 16 gray levels that
  previews what Glassly CFW glasses can show.
- **Controls**: the touch bar (tap A and tap B, double tap, hold, swipes), look up and
  down, speech the glasses hear (typed, delivered as a transcription), phone
  notifications, battery, location, and connecting or disconnecting the
  glasses. Tap A and tap B are single taps with `index` 0 and 1, the two
  fingers a Neural Band tells apart (`glassly sim tap` / `glassly sim tap --b`).
  Button presses come from `glassly sim button`.
- **Phone**: your UI page with the same `glassly` bridge, safe-area insets and
  capsule menu it gets inside the Glassly App. Switch it to a folded iPhone Duo
  (or run `glassly sim phone duo`) to check the page against the 84 pt status
  rail on the right, with the capsule and any `useRailBackButton` back button
  drawn in the rail. The same page is at `/ui/` on the simulator's address if
  you want it in its own tab.
- **Log, Scene, State**: console output, the elements on the display, and what
  the miniapp is subscribed to.

## Drive it from the terminal

While a simulator is running, `glassly sim <command>` from the project folder
talks to it:

```bash
glassly sim --detach            # start in the background and return when ready
glassly sim screen              # what is on the glasses, one element per line
glassly sim screenshot out.png  # the display as a PNG
glassly sim tap                 # also: double-tap, hold, swipe-up, swipe-down, look-up, look-down
glassly sim button long
glassly sim phone duo           # folded iPhone Duo phone page; back with: glassly sim phone iphone
glassly sim say "what's the weather"
glassly sim notify --title "Mom" --content "Call me back"
glassly sim location 48.8566 2.3522
glassly sim ui request places:autocomplete '{"query": "cafe"}'
glassly sim logs --since 0      # console output from both layers, plus build errors
glassly sim status --json
glassly sim stop
```

`screen` prints the processed frame, which is usually the quickest check:

```
Simulated Glasses 576x288, view main
text     title            @ 286,14 150x27  "TETRIS" {"color":15}
rect     frame            @ 138,12 134x264 {"border":1,"color":7}
```

`ui send` and `ui request` act as the phone page, so background logic that
answers the page can be exercised without a browser. To drive the real page, open
`http://localhost:<port>/ui/` in any browser or browser automation tool.

The full list is in the [CLI reference](https://docs.glassly.ai/app-devs/reference/cli.md#sim).

## What is simulated

| Area | In the simulator |
| --- | --- |
| `session.display` | Rendered and reported exactly as the host processes it, including `degraded` and `dropped`. |
| `session.input`, `session.imu.onHeadPosition` | Touch gestures, head up and down, button presses. |
| `session.transcription`, `session.translation` | Text you send with `say` and `translate`. No audio is captured. |
| `session.speaker` | `speak()` and `play()` are logged and resolve after a simulated duration. The window can read speech aloud. |
| `session.storage` | Kept on disk per package in `~/.glassly/sim/`. |
| `session.ui` and the `glassly` page bridge | Complete, including RPC and cancellation. |
| `session.location`, `session.glasses`, `session.phone.notifications`, battery | Values you set. |
| `session.system` (open URL, clipboard, share), `session.led` | Logged, not performed. |
| Manifest permissions | Enforced the same way: an undeclared permission fails with `PERMISSION_NOT_DECLARED`. |

Camera, microphone audio, streaming, navigation, `session.ai`, `session.auth`,
`session.blob`, `session.memory`, and miniapp-to-miniapp calls are not simulated.
A call to one of them fails with `NOT_IMPLEMENTED`, and the simulator names it in
the log and under **State**. Test those on a phone with `glassly dev`.

The simulator is a preview, not the hardware. Text is drawn with your
computer's sans-serif face at the device's glyph advances, so line breaks match
and letter shapes do not. Timing, brightness, and Bluetooth throughput are not
modelled. Check on glasses before you ship.

## Next steps

- [Quickstart](https://docs.glassly.ai/app-devs/getting-started/quickstart.md)
Run the same project on a phone and glasses.
- [AI IDE integration](https://docs.glassly.ai/app-devs/getting-started/ai-ide-integration.md)
Tell your coding agent how to use the simulator.
