@quicktvui/ai-cli

QuickTVUI skill runtime CLI.

Install

npm install -g @quicktvui/ai-cli @quicktvui/ai-skills

Starting from @quicktvui/[email protected], global install/upgrade auto-runs quicktvui-ai update to sync:

• ~/.agents/skills/quicktvui
• ~/.gemini/GEMINI.md bridge block
• ~/.gemini/settings.json context file names

Set QUICKTVUI_AI_SKIP_POSTINSTALL=1 to disable auto-sync.

Commands

quicktvui-ai init
quicktvui-ai doctor
quicktvui-ai validate
quicktvui-ai update
quicktvui-ai create-project quick-tv-app
quicktvui-ai setup-vue-env --project ./quick-tv-app
quicktvui-ai setup-android-env --project ./quick-tv-app
quicktvui-ai setup-all-env --project ./quick-tv-app
quicktvui-ai run-dev --project ./quick-tv-app
quicktvui-ai run-esapp --project ./quick-tv-app --pkg es.hello.world
quicktvui-ai prompt --lang zh

# alias commands for create-project
quicktvui-ai-create-project quick-tv-app
quicktvui-aicreate-project quick-tv-app

Default install path

• ~/.agents/skills/quicktvui

Options

• --dir <path>: custom skill path
• --project <path>: custom project root for rule checks
• --dest <path>: destination base directory for create-project
• --offline: use bundled template directly for create-project
• --skip-install: skip dependency install for create-project
• --strict: fail on doctor check issues
• --lang <code>: prompt language for prompt command (zh or en)
• --gemini-dir <path>: custom Gemini config directory (default ~/.gemini, or $GEMINI_CLI_HOME/.gemini)
• --skip-gemini-config: skip updating Gemini bridge config during init/update
• --node-major <n>: target Node.js LTS major for setup-vue-env (default 20)
• --skip-node-install: skip Node.js install stage in setup-vue-env
• --force-node-install: force Node.js install stage in setup-vue-env
• --skip-yarn-install: skip yarn global install in setup-vue-env
• --skip-project-install: skip project dependency install in setup-vue-env
• --auto-emulator <true|false>: auto create/start emulator when no adb device
• --adb-path <path>: custom adb path/command (or use env QUICKTVUI_ADB_PATH)
• --device-ip <ip[:port]>: preferred real device endpoint for adb connect
• --device <serial>: explicit target adb serial for setup-android-env / run-esapp
• --allow-non-tv-device <true|false>: allow phone/tablet target for TV run flow (default false)
• --avd-name <name>: custom AVD name for setup-android-env
• --headless: start emulator with -no-window -no-audio
• --runtime-version <version>: pin runtime version in direct mode
• --runtime-url <url>: use custom runtime apk url in direct mode
• --server-host <ip>: override debug server host IP
• --force-runtime-install: force reinstall runtime in direct mode
• --skip-runtime-setup: skip runtime setup in setup-android-env/run-dev
• --auto-load-local-bundle <true|false>: auto trigger runtime to load local bundle in run-dev
• --port <n>: dev server port used by run-dev auto load (default 38989)
• --skip-env-check: skip environment stage in run-dev
• --runtime-package <pkg>: runtime package for run-esapp (default com.extscreen.runtime)
• --esapp-uri <uri>: raw launch URI (esapp://)
• --esapp-query <json>: extra query params JSON merged in structured mode
• --pkg --ver --min-ver --repository --uri --from --args --exp --flags --use-latest: structured esapp://action/start params

Typical flow

quicktvui-ai init
quicktvui-ai doctor

Then reload your AI agent so it rescans local skills.

init/update also auto-maintains Gemini global context files:

• updates ~/.gemini/GEMINI.md with QuickTVUI @.../SKILL.md bridge block
• ensures ~/.gemini/settings.json contains context.fileName entries: GEMINI.md, AGENTS.md, SKILL.md, CONTEXT.md

Create project with network fallback

quicktvui-ai create-project quick-tv-app

This command:

1. Tries to clone quicktvui-template from GitHub.
2. Falls back to the bundled local template if clone fails.
3. Updates package.json (name, version).
4. Ensures @quicktvui/ai exists in devDependencies.
5. Installs dependencies (yarn install, or npm install fallback).

Configure Android env (device/emulator + runtime)

quicktvui-ai setup-android-env --project ./quick-tv-app

This command:

1. Detects Android SDK root (auto creates a default SDK root when missing).
2. Detects Android SDK/adb/emulator tools. @quicktvui/ai-cli does not bundle adb.
3. Verifies target device looks like TV (leanback / television feature). Use --allow-non-tv-device true only if you intentionally target phone/tablet.
4. In non-interactive mode, requires explicit --device <serial> when adb devices are connected.
5. If sdkmanager/avdmanager is missing, it auto-downloads and installs official Android Command-line Tools.
6. If adb is missing, it auto-installs platform-tools (with size estimate + sdkmanager progress).
7. Detects connected adb devices, and asks whether to use connected device.
8. If user doesn't use connected device (or no device exists), it asks for real-device IP and runs adb connect.
9. If still no real device, asks whether to download/start official Google Android emulator.
10. Checks Google repository reachability before emulator download; if unavailable, asks user to install emulator manually.
11. Prints estimated download size and then starts sdkmanager download (progress shown by sdkmanager).
12. Installs runtime APK and configures debug server host.
13. If runtime already exists, asks whether to reinstall runtime before run.
14. Launches runtime app and waits it enters running state.

Configure Vue env (Node + package manager)

quicktvui-ai setup-vue-env --project ./quick-tv-app

This command:

1. Ensures Node.js LTS (macOS/Windows auto install).
2. Ensures yarn is installed globally.
3. Installs project dependencies (yarn install or npm install fallback).

Configure All Dev Envs

quicktvui-ai setup-all-env --project ./quick-tv-app

This command runs setup-vue-env and setup-android-env sequentially.

Run development server

quicktvui-ai run-dev --project ./quick-tv-app

This command:

1. Runs setup-android-env by default.
2. Starts project dev script (yarn dev, pnpm dev, or npm run dev).
3. Waits for local server port (default 38989) and auto triggers runtime to load local bundle.
4. Supports run-esapp structured options (--pkg/--ver/--repository/...) or --esapp-uri to override auto launch URI.

Run ES app by protocol

# structured mode (recommended for AI)
quicktvui-ai run-esapp --project ./quick-tv-app --pkg es.hello.world --from cmd

# local dev bundle
quicktvui-ai run-esapp --project ./quick-tv-app --pkg es.hello.world --uri 192.168.1.10:38989

# remote repository + pinned version
quicktvui-ai run-esapp --project ./quick-tv-app --pkg liulipeng/com.zoo --ver 1.0.0 --repository http://repo.quicktvui.com/repository/rpk

# raw URI passthrough (full compatibility)
quicktvui-ai run-esapp --esapp-uri 'esapp://action/start?from=cmd&pkg=es.hello.world&uri=assets://hello.rpk'

Full protocol reference: docs/esapp-protocol.md

Generate LLM install prompt

quicktvui-ai prompt --lang zh

Installer scripts

• scripts/install (bash)
• scripts/install.ps1 (PowerShell)