@cuelight/cli

幕启官方命令行工具。你可以用它调用幕启开放 API 生成图片/视频，也可以让 Codex、WorkBuddy、OpenClaw、Hermes 等外部 Agent 通过稳定命令读取项目状态、写回剧本/分镜，并推进短剧制作工作流。

适合这些场景：

• 用命令行生成图片、图生图、文生视频、图生视频。
• 让外部 Agent 自动读取幕启项目事实，并把文本、角色、场景、分镜写回项目。
• 在脚本或 CI 中查询任务状态、导出视频、检查项目进度。

安装

推荐使用一键安装脚本。脚本会全局安装幕启 Agent Skills 和 cuelight-cli。

Windows PowerShell:

powershell -ExecutionPolicy Bypass -c "irm https://cuelight.app/cli_install.ps1 | iex"

macOS / Linux:

curl -fsSL https://cuelight.app/cli_install.sh | bash

如果 npm 访问较慢，可使用国内镜像重试：

powershell -ExecutionPolicy Bypass -c "$env:CUELIGHT_NPM_REGISTRY='https://registry.npmmirror.com'; irm https://cuelight.app/cli_install.ps1 | iex"

curl -fsSL https://cuelight.app/cli_install.sh | CUELIGHT_NPM_REGISTRY=https://registry.npmmirror.com bash

只安装 CLI 时，也可以直接使用 npm：

npm install -g @cuelight/cli

安装完成后验证：

cuelight-cli --version

配置 API Key

在幕启「开放平台 → API Key」创建密钥，然后写入本机配置：

cuelight-cli config set api-key <your_api_key>
cuelight-cli config show

config show 会脱敏显示 API Key。不要把真实 API Key 发到公开聊天、日志或 issue 中。

也可以只对单次命令传入 API Key：

cuelight-cli --api-key <your_api_key> project list

给外部 Agent 的一键提示词

如果你希望外部 Agent 帮你安装并配置幕启工作流，请先生成 API Key，把下面的 <替换为你的API_KEY> 替换成真实 key 后，整段发给 Agent：

请帮我安装幕启外部 Agent 工作流：
1. 判断当前系统：Windows 使用 PowerShell，macOS/Linux 使用 bash。
2. Windows 执行：powershell -ExecutionPolicy Bypass -c "irm https://cuelight.app/cli_install.ps1 | iex"
3. macOS/Linux 执行：curl -fsSL https://cuelight.app/cli_install.sh | bash
4. 如果 npm 访问较慢，请设置 CUELIGHT_NPM_REGISTRY=https://registry.npmmirror.com 后重试对应安装脚本。
5. 安装后运行 cuelight-cli --version 检查是否可用。
6. 配置 API Key：cuelight-cli config set api-key <替换为你的API_KEY>
7. 运行 cuelight-cli config show 检查配置是否生效；输出里的 api-key 应该是脱敏显示。

生成图片和视频

--model 没有默认值。先查询当前可用模型，再提交生成任务。

cuelight-cli image models
cuelight-cli video models

文生图：

cuelight-cli image generate \
  --prompt "赛博朋克城市的猫" \
  --model seedream-5.0-lite \
  --size 16:9 \
  --output out.png

图生图：

cuelight-cli image generate \
  --prompt "改成夜景霓虹短剧海报质感" \
  --model seedream-5.0-lite \
  --image-urls ./reference.png \
  --output poster.png

文生视频：

TASK=$(cuelight-cli video generate \
  --prompt "日落下的海岸" \
  --model seedance-2-0-fast \
  --duration 5 \
  --aspect-ratio 9:16 \
  --json | jq -r .task_id)

cuelight-cli task wait "$TASK" --output out.mp4

图生视频：

cuelight-cli video generate \
  --prompt "镜头从人物正面缓慢推近，雨夜霓虹反射" \
  --model seedance-2-0-fast \
  --image-urls ./first-frame.png \
  --duration 5 \
  --aspect-ratio 9:16 \
  --output out.mp4

本地参考图会由 CLI 自动临时上传，不需要手动调用文件上传命令。

短剧项目工作流

常用项目状态命令：

cuelight-cli project list --json
cuelight-cli project status <projectId> --json
cuelight-cli director status <projectId> --json
cuelight-cli director storyboard-status <episodeId> --json
cuelight-cli episode status <episodeId> --json

常用写回命令：

cuelight-cli bible set-world <projectId> --file ./world.txt
cuelight-cli director set-style-prompt <projectId> --file ./style-prompt.txt
cuelight-cli season set-proposal <projectId> <seasonId> --file ./proposal.txt
cuelight-cli season set-design <projectId> <seasonId> --file ./design.txt
cuelight-cli episode set-outline <episodeId> --file ./episode-outline.txt
cuelight-cli episode set-script <episodeId> --file ./episode-script.txt
cuelight-cli director import-storyboards <episodeId> --file ./storyboards.json

把项目原文和切片物化到本地，方便外部 Agent 读取上下文：

cuelight-cli source materialize <projectId> --json

默认输出到：

./.cuelight/<projectId>/source/original.txt
./.cuelight/<projectId>/source/chunks/<chunkId>.txt
./.cuelight/<projectId>/source/source-manifest.json

自动化脚本和外部 Agent 推荐始终使用 --json，便于稳定解析。

全局参数

| 参数 | 说明 | |------|------| | --api-key <key> | 覆盖 API Key；环境变量为 CUELIGHT_API_KEY | | --url <url> | 覆盖幕启服务地址；默认 https://cuelight.app | | --project-id <id> | 设置默认项目 ID；环境变量为 CUELIGHT_PROJECT_ID | | --json | 输出 JSON，适合脚本和 Agent 解析 |

故障排查

平台二进制缺失或权限异常：

cuelight-cli doctor fix-binary

命令不存在：

• 重新打开终端。
• 检查 npm 全局 bin 目录是否在 PATH 中。
• 重新运行一键安装脚本或 npm install -g @cuelight/cli。

npm 安装较慢：

curl -fsSL https://cuelight.app/cli_install.sh | CUELIGHT_NPM_REGISTRY=https://registry.npmmirror.com bash

API Key 鉴权失败：

cuelight-cli config set api-key <your_api_key>
cuelight-cli config show

确认 API Key 来自「开放平台 → API Key」，且当前账号具备开放 API 权限。

支持平台

@cuelight/cli 使用预编译二进制分发，安装后运行不需要 Bun。

• macOS x64
• macOS arm64
• Windows x64
• Linux x64 (glibc)
• Linux x64 (musl / Alpine)

公开 CLI 面向用户和外部 Agent 工作流，不包含幕启内部 chat/agent 调试命令。运行：

cuelight-cli --help
cuelight-cli <command> --help

查看当前版本支持的完整命令。