npm package: @quicktvui/ai-cli
Description: CLI for installing and validating QuickTVUI AI skills
Author: QuickTVUI
Latest version: 1.1.22

# @quicktvui/ai-cli

QuickTVUI skill runtime CLI.

## Install

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

Starting from `@quicktvui/ai-cli@1.1.22`, 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

```bash
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

```bash
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

```bash
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)

```bash
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)

```bash
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

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

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

## Run development server

```bash
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

```bash
# 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`](./docs/esapp-protocol.md)

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

```bash
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`.

```bash
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:

```bash
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:

```bash
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

```bash
quicktvui-ai prompt --lang zh
```

## Installer scripts

- `scripts/install` (bash)
- `scripts/install.ps1` (PowerShell)