@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 debug-targets --base-url http://127.0.0.1:38989
quicktvui-ai debug-events --client-id 192.168.1.10 --limit 100
quicktvui-ai debug-native-logs --client-id 192.168.1.10 --limit 100
quicktvui-ai debug-screenshot --client-id 192.168.1.10 --project ./quick-tv-app
quicktvui-ai plugin-create-project plugin/demo-plugin --package-name com.qtapp.plugin.demo
quicktvui-ai plugin-build plugin/demo-plugin
quicktvui-ai plugin-create-module --project plugin/demo-plugin --description "展示设备信息"
quicktvui-ai plugin-create-component --project plugin/demo-plugin --description "展示二维码"
quicktvui-ai plugin-enable-api --device <serial>
quicktvui-ai plugin-check --device <serial>
quicktvui-ai plugin-status --device <serial>
quicktvui-ai runtime-status --device <serial>
quicktvui-ai plugin-upload-so --device <serial> --tag eskit.so.ffmpeg.command --file docs/plugin/armeabi-v7a.zip
quicktvui-ai plugin-upload-plugin --device <serial> --pkg eskit.plugin.imagequality --file docs/plugin/plugin-general-debug.apk
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>: deprecated (Google emulator auto-download flow removed)
• --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 in multi-device mode (default false)
• --avd-name <name>: deprecated (Google AVD flow removed)
• --headless: deprecated (Google AVD flow removed)
• --runtime-version <version>: pin runtime version for hub-first download mode
• --runtime-channel <release|debug>: choose fallback channel when hub download fails (default release, auto-fallback to debug when release metadata is pending/unavailable)
• --runtime-url <url>: use custom runtime apk url (skip hub/fallback metadata resolution)
• --server-host <ip>: override debug server host IP
• --force-runtime-install: force reinstall runtime
• --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
• --base-url <url>: ESDebugServer base URL for debug-* commands (default http://127.0.0.1:38989)
• --plugin-base-url <url>: explicit plugin server base URL override for plugin-* commands
• If --plugin-base-url is omitted, plugin commands first try the adb-connected device service URL; if the host cannot be inferred or no adb device is connected, provide the service address explicitly (for example http://192.168.1.100:36366)
• Plugin server endpoints are POST-only; the same paths may return 404 for GET
• --mode <create|update>: mode for plugin-create-project
• --template-repo <url>: custom plugin template repo for plugin-create-project
• --package-name <pkg>: Java package name for plugin project/module/component generation
• --workspace-root <path>: workspace root used to inject build:android-plugin
• --description <text>: feature description for plugin-create-module / plugin-create-component
• --class-name <name>: explicit generated class name for plugin module/component
• --view-class-name <name>: explicit View class name for plugin-create-component
• --view-base-class <name>: Android base View class for plugin-create-component
• --methods <json|csv>: exported module method list for plugin-create-module
• --props <json|csv>: component prop list for plugin-create-component
• --events <json|csv>: component event list for plugin-create-component
• --functions <json|csv>: component function list for plugin-create-component
• --register <true|false>: whether to patch Application#onCreate registration (default true)
• --app-file <path>: explicit Application source file to patch
• --src-root <path>: explicit Android source root such as app/src/main/java
• --docs-dir <path>: explicit docs/component output directory
• --native-tag-name <name>: explicit kebab-case native tag for generated component
• --wrapper-tag-name <name>: explicit kebab-case wrapper tag for generated component
• --client-id <id>: target clientId for debug-context / debug-events / debug-native-logs / debug-screenshot
• --hash <hash>: optional target hash for debug-targets / debug-context / debug-native-logs
• --limit <n>: result limit for debug-events / debug-native-logs
• --kind <kind>: event kind filter for debug-events
• --since-seq <n>: sinceSeq filter for debug-events
• --refresh <true|false>: refresh native logs before reading (default true)
• --output <path>: output file path for debug-screenshot
• --include-data <true|false>: include base64 screenshot payload in debug-screenshot output
• --timeout-ms <n>: request timeout for debug-* commands (default 15000)
• --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
• --enabled <true|false>: value for plugin-enable-api (default true)
• --abi <abi>: target ABI for plugin-upload-so (default: read from ro.product.cpu.abi)
• --file <path>: local zip/apk file for plugin-upload-so or plugin-upload-plugin
• --file-name <name>: override multipart upload filename for plugin uploads

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 + 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 tools. @quicktvui/ai-cli does not bundle adb.
3. Device selection rule:
   • if only one device is connected, skip TV/phone distinction
   • if multiple devices are connected, classify TV-like vs phone/tablet and require target serial selection
   • emulator is treated as TV-like device
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. If no connected device exists, it asks for real-device IP and runs adb connect.
8. If still no device exists, it stops and asks user to manually install/start emulator (recommended: https://mumu.163.com) or connect device first.
9. In multi-device mode, non-TV target requires confirmation (or --allow-non-tv-device true).
10. Installs runtime APK (hub first, then gitee/github fallback with SHA256 verification) and configures debug server host.
11. If runtime already exists, asks whether to reinstall runtime before run.
12. 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.
5. If you need to confirm whether the quick app really loaded successfully or whether runtime reported an error, run quicktvui-ai runtime-status --device <serial>.

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

After run-esapp, if you need to confirm whether launch succeeded or inspect the latest runtime-side load error, run:

quicktvui-ai runtime-status --device <serial>

Read runtime debug data without MCP

If MCP is unavailable but ESDebugServer is already running, AI can still read debug data directly through quicktvui-ai.

quicktvui-ai debug-targets --base-url http://127.0.0.1:38989
quicktvui-ai debug-context --client-id <clientId>
quicktvui-ai debug-events --client-id <clientId> --limit 100
quicktvui-ai debug-native-logs --client-id <clientId> --limit 100
quicktvui-ai debug-screenshot --client-id <clientId> --project ./quick-tv-app

Notes:

1. debug-targets returns the current /ai/targets list from ESDebugServer.
2. debug-events reads recent unified runtime events (console / exception / network / screenshot / native-log).
3. debug-native-logs reads Android native logs for the selected target.
4. debug-screenshot saves the latest screenshot to <project>/.quicktvui-ai/debug-screenshots/ by default and prints the saved file path.

Debug TV plugin server without MCP

If the AI needs to inspect or upload plugin assets on TV and only CLI execution is available, use this order:

quicktvui-ai plugin-enable-api --device <serial>
quicktvui-ai plugin-check --device <serial>
quicktvui-ai plugin-status --device <serial>
quicktvui-ai runtime-status --device <serial>
quicktvui-ai plugin-upload-so --device <serial> --tag eskit.so.ffmpeg.command --pkg eskit.so.ffmpeg.command --file docs/plugin/armeabi-v7a.zip
quicktvui-ai plugin-upload-plugin --device <serial> --pkg eskit.plugin.imagequality --file docs/plugin/plugin-general-debug.apk
quicktvui-ai plugin-delete-so --device <serial> --pkg eskit.so.ffmpeg.command --abi armeabi-v7a
quicktvui-ai plugin-delete-plugin --device <serial> --pkg eskit.plugin.imagequality
quicktvui-ai plugin-server-ui --device <serial>

Notes:

1. plugin-enable-api sends Toolkit broadcast eskit.sdk.core.ACTION_TOOLKIT_SETTING with RESTFUL_API=true.
2. plugin-check treats uploadSo / uploadPlugin / deleteSo / deletePlugin returning 400 missing-parameter errors as expected health signals.
3. plugin-status returns the full /status view, including runtime-loaded state (installedSoList / installedPluginList), uploaded records (uploadedSoList / uploadedPluginList), and compatible legacy fields.
4. runtime-status also reads /status, but surfaces data.rpkLoadStatus first and falls back to data.loadStatus for recent load state and latest error messages after quick app/plugin load.
5. plugin-delete-so / plugin-delete-plugin can delete one uploaded record or clear all records with --pkg all; deleting currently loaded bytes may still require a host/runtime restart to take effect.
6. plugin-server-ui starts a local HTML dashboard for status, upload, delete, and clear actions without needing handwritten curl commands.
7. plugin-upload-so auto-detects ro.product.cpu.abi from the selected device when --abi is omitted.
8. If the selected device host cannot be inferred, the CLI will ask for the service address in interactive mode; if you leave it blank, the command stops. In non-interactive mode, pass --plugin-base-url explicitly.
9. /api/v1/hello / /api/v1/status / /api/v1/uploadSo / /api/v1/uploadPlugin / /api/v1/deleteSo / /api/v1/deletePlugin all use POST; do not use GET to probe them.
10. Default test identifiers are eskit.so.ffmpeg.command and eskit.plugin.imagequality.
11. Plugin-related TV validation requires runtime >= v2.9.1585; if the detected runtime on the selected TV is lower, ask whether to uninstall and reinstall runtime before continuing.

Scaffold Android plugin projects/modules/components

Use this workflow when AI needs to create or package Android plugin code without manually editing every file:

quicktvui-ai plugin-create-project plugin/demo-plugin \
  --workspace-root . \
  --package-name com.qtapp.plugin.demo

quicktvui-ai plugin-build plugin/demo-plugin

quicktvui-ai plugin-create-module \
  --project plugin/demo-plugin \
  --description "展示设备信息" \
  --methods "showInfo,getInfo"

quicktvui-ai plugin-create-component \
  --project plugin/demo-plugin \
  --description "展示二维码" \
  --props '[{"name":"content","type":"String","description":"二维码内容"}]' \
  --events onRendered \
  --functions refresh

Notes:

1. plugin-create-project writes .kyy-plugin-project.json and injects build:android-plugin when the plugin lives under a workspace subdirectory.
2. For long-lived or releasable plugins, prefer a visible root path such as plugin/demo-plugin; do not default plugin projects to hidden directories like .ai-test/*.
3. plugin-build uses fixed priority: build:android-plugin -> build:plugin -> build -> ./gradlew assembleGeneralDebug.
4. plugin-create-module generates code against com.quicktvui.sdk.base.module.IEsModule.
5. plugin-create-component generates code against com.quicktvui.sdk.base.component.IEsComponent / IEsComponentView, creates docs/component/<kebab-name>.md, and keeps tags in kebab-case.

Generate LLM install prompt

quicktvui-ai prompt --lang zh

Installer scripts

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