@cuelight/cli

CueLight 的命令行工具，用于通过 CLI 管理项目、角色、场景、分镜、视频与相关资源。对外部 agent 而言，CLI 是读取项目事实、保存文字资源、提交图片/视频任务的主要入口。

公开边界

• 公开 CLI 只提供资源读取、资源保存/更新、状态汇总、图片/视频/语音任务提交与轮询导出
• 文本内容默认由外部 agent 自行生成，再通过 CLI 写回
• 不通过公开 CLI 暴露 CueLight 内部 chat/agent 交互
• 内部调试和旧文本 AI 能力保留在 cuelight-cli internal ...，不出现在根 help 中

运行时要求

• 预编译二进制分发，安装后运行不需要 Bun
• 当前支持以下平台：
  • macOS x64
  • macOS arm64
  • Windows x64
  • Linux x64 (glibc)
  • Linux x64 (musl / Alpine)

安装

bun add -g @cuelight/cli

也支持：

npm install -g @cuelight/cli

安装完成后可直接验证：

cuelight-cli --version

若当前平台不在支持列表内，安装器会提示找不到匹配的本地二进制包。 若平台子包缺失、二进制文件损坏或缺少执行权限，可执行：

cuelight-cli doctor fix-binary

doctor fix-binary 同时支持本地项目安装和全局安装，会自动选择合适的包管理器并尝试补装对应平台子包。

使用

cuelight-cli --help
cuelight-cli --version
cuelight-cli project list --help
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 ./.cuelight/<projectId>/world.txt

Director 命令组

director 提供给外部 agent 使用的稳定导演原语，定位是：

• 状态读取：director status / visual-status / storyboard-status / video-status
• 视觉配置：director configure-visuals / set-style-prompt / generate-style-image
• 分镜操作：director import-storyboards / update-storyboard
• 视频操作：director generate-video / batch-generate-videos / wait-task / export-videos
• 资产操作：公开 character / scene / prop 命令组分别管理角色、场景、道具与参考图

对于外部 agent，推荐始终使用 --json，并按 agent-skills/cuelight-drama/references/director.md 中定义的字段契约消费输出。

Internal 命令

若需要开发/排障用途的内部能力，可显式使用：

cuelight-cli internal workflow my-script-e2e --file ./test-data/test-08.txt
cuelight-cli internal director generate-storyboards <episodeId> --wait

这些命令不属于公开 agent 操作面，skill 也不会引用。

配置

cuelight-cli config show
# 默认连接 https://cuelight.app，如需本地服务请显式覆盖
cuelight-cli config set url http://localhost:3000
cuelight-cli config set api-key <key>