xg.glass SDK

CLI Reference

CLI commands for running a single Kotlin file or a generated project.

Install

Install the published CLI from PyPI:

pip install xg-glass
xg-glass --help

Use doctor when setting up a machine:

xg-glass doctor
xg-glass doctor --offline

Inside an already-generated project that contains xg-glass.yaml, build, install, and project run work as-is. Commands that create or synthesize a project need SDK source/templates. The PyPI CLI downloads the matching tagged SDK archive into ~/.xg-glass/sdk/ on first use, or you can force a checkout with --sdk:

git clone https://github.com/hkust-spark/xg-glass-sdk
xg-glass init /path/to/myapp --sdk /path/to/xg-glass-sdk
xg-glass run /path/to/MyEntry.kt --sdk /path/to/xg-glass-sdk

Managed Android command-line tools downloads are SHA-256 verified before extraction. From a repository checkout, you can also use the repo-local launcher at /path/to/xg-glass-sdk/xg-glass.

xg-glass doctor

Diagnose the local CLI environment.

Options:

  • --offline: skip best-effort network checks

xg-glass validate

Run a guided hardware-validation pass for one device and write a paste-ready Markdown issue report. The runner does not automate BLE pairing or glasses gestures; it uses generated-app logcat markers where available and prompts for manual PASS/FAIL/SKIP otherwise.

xg-glass validate --devices simulator
xg-glass validate --devices rayneo --serial <adb-serial>

Options:

  • --devices <device>: required; exactly one of rokid, rayneo, meta, frame, omi, even, inmo, or simulator
  • --serial <id>: adb device serial
  • --sdk <path>: SDK repo root override
  • --report <path>: Markdown report path
  • --keep-project: keep the generated validation project

Bare-file quick mode

Run a single Kotlin file by letting the CLI generate a temporary project:

xg-glass run /path/to/MyEntry.kt --sdk /path/to/xg-glass-sdk

Constraints:

  • the .kt file must contain a package ... line
  • the file must contain a top-level class/object (used to infer the entry class)

Common options:

  • --entry-class <fqcn>: override inference
  • --sdk <path/to/sdk-repo>: override the resolved SDK checkout/cache path
  • --save ./myapp: persist the generated project
  • --keep-tmp: keep the temporary directory for debugging
  • --sim: build for Android Emulator (x86_64) and enable the simulator backend
  • --devices <list>: quick mode only; comma-separated devices to include: rokid, rayneo, meta, frame, omi, even, inmo, simulator, or all. --sim adds simulator.
  • --local_video <path>: simulator mode only; use a local video file as the capturePhoto source
  • --video_url <url>: simulator mode only; download a YouTube/Bilibili video and use it as the capturePhoto source
  • --serial <id>: adb device serial
  • --variant <name>: build variant (default: debug)
  • --module <name>: app module name (default: app)

--devices is only accepted when the command includes a .kt quick-mode file:

xg-glass run /path/to/MyEntry.kt --devices even,simulator

Video options require --sim:

xg-glass run /path/to/MyEntry.kt --sdk /path/to/xg-glass-sdk --sim --local_video /path/to/video.mp4
xg-glass run /path/to/MyEntry.kt --sdk /path/to/xg-glass-sdk --sim --video_url <youtube-or-bilibili-url>

When --sim starts an Android Emulator, the launcher appends arguments from XG_EMULATOR_ARGS after -no-snapshot-load.

Project workflow

xg-glass init <dir>

Create a minimal developer project from the template. The PyPI CLI resolves the matching SDK automatically; pass --sdk when you want to force a local checkout:

xg-glass init ./myapp

Common options:

  • --sdk <path>: SDK repo root. When this points at a checkout, --template defaults to <resolved-sdk>/templates/kotlin-app.
  • --template <path>: template directory override
  • --entry-class <fqcn>: entry class to write into config/manifest (default: com.example.xgglassapp.logic.ExampleAppEntry)
  • --sim: create project for simulation
  • --devices <list>: comma-separated devices to include: rokid, rayneo, meta, frame, omi, even, inmo, simulator, or all (default). --sim adds simulator.
  • --no-shell-setup: print shell setup instructions instead of updating shell startup files

Explicit device selections are written to xg-glass.yaml in the generated project. Without --devices, the template keeps the all-device demo path.

From an SDK repository checkout, the local launcher can infer the SDK path:

/path/to/xg-glass-sdk/xg-glass init ./myapp

xg-glass build

Build the phone-side APK.

Common options:

  • --project <dir>: project root (default: current directory)
  • --config <path>: config path (default: xg-glass.yaml)
  • --variant <name>: build variant (default: debug)
  • --module <name>: app module name (default: app)
  • --entry-class <fqcn>: override entryClass
  • --sdk <path>: override sdkPath
  • --rayneo-aar-dir <path>: override RayNeo vendor AAR directory

Example:

cd ./myapp
xg-glass build

xg-glass install

Install the phone-side APK via ADB.

Common options:

  • --project <dir>: project root (default: current directory)
  • --config <path>: config path (default: xg-glass.yaml)
  • --variant <name>: build variant (default: debug)
  • --module <name>: app module name (default: app)
  • --serial <id>: adb device serial
  • --apk <path>: explicit APK path

Example:

cd ./myapp
xg-glass install

xg-glass run

Without a .kt argument, launch an already-built generated project via ADB.

Common options:

  • --project <dir>: project root (default: current directory)
  • --config <path>: config path (default: xg-glass.yaml)
  • --variant <name>: build variant (default: debug)
  • --module <name>: app module name (default: app)
  • --serial <id>: adb device serial
  • --package <applicationId>: override applicationId

Example:

cd ./myapp
xg-glass run