@dlazy/cli

English · 中文

@dlazy/cli 提供 dlazy 终端命令，方便在 Shell 管道中运行 dLazy 的 AI 工具。

每条命令输出统一的 ToolResult 信封，一个工具的输出可直接管道喂给下一个。

访问 https://dlazy.com/docs** 获取更多信息。

安装

# 全局安装（把 `dlazy` 加入 PATH）
npm install -g @dlazy/cli

# 项目内（通过 `npx dlazy ...` 调用）
npm install @dlazy/cli
# 或：pnpm add @dlazy/cli   |   yarn add @dlazy/cli

登录认证

dlazy login                 # 设备码流程，浏览器扫码授权后保存到 ~/.dlazy/config.json
dlazy login --local         # 使用 http://localhost:3000，便于本地服务端联调
dlazy auth set sk-xxxx      # 直接写入 Token
dlazy auth get              # 查看当前 Token（已脱敏）
dlazy auth get --show       # 显示完整 Token
dlazy logout                # 从配置中清除 Token

运行时的 API Key 解析顺序：--api-key 参数 → DLAZY_API_KEY 环境变量 → ~/.dlazy/config.json → 交互式登录（仅在 TTY 下触发）。

CLI 快速上手

# 单图生成
dlazy gpt-image-2 --prompt "雨夜赛博朋克猫"

# 两个工具串成管道（自动解析上游产物）
dlazy gpt-image-2 --prompt "侦探侧脸" \
  | dlazy veo-3.1 --image - --prompt "雨夜镜头推进"

# 列出 / 详查工具
dlazy tools list
dlazy tools describe gpt-image-2

# 异步任务：先提交，后查询
dlazy veo-3.1 --image hero.png --prompt "..." --no-wait
dlazy status gen_abc123 --wait

全局参数

语言也会按 DLAZY_LANG → LC_ALL → LANG 顺序回退识别。

单次运行参数（每个工具命令通用）

输出模式 --format

stderr 始终是给人看的进度提示；stdout 由 --format 决定。

要保存生成的素材，用 --save（自动下载、建目录、重试）：

dlazy gpt-image-2 --prompt "logo" --save logo.png

# script 输出结构化分镜 JSON；用 jq 提取 markdown 渲染
dlazy script --prompt "6 个流浪猫的电影分镜" \
  | jq -r '.result.outputs[0].value.texts[0]' > script.md

# 默认 JSON 模式 + jq，直接取信封字段
dlazy gpt-image-2 --prompt "..." | jq -r '.result.outputs[0].url'
dlazy veo-3.1 --image hero.png --prompt "..." \
  | jq 'if .ok then .result else .message end'

管道引用语法

CLI flag 值可使用引用语法，从上游 stdin 信封里取数据。所有引用在网络请求前替换完成。

示例：

# 1) 单图自动接到视频
dlazy gpt-image-2 --prompt "..." \
  | dlazy veo-3.1 --image - --prompt "雨夜推进"

# 2) 取 4 张图里第 2 张
dlazy gpt-image-2 --batch 4 --prompt "..." \
  | dlazy veo-3.1 --image @1.url --prompt "缓推"

# 3) 数组字段：上游全部 url 自动展开
dlazy gpt-image-2 --batch 4 --prompt "..." \
  | dlazy merge --videos -

# 4) script 输出的分镜文本驱动下一个 prompt
dlazy script --prompt "6 个流浪猫的电影分镜" \
  | dlazy gpt-image-2 --prompt @stdin:result.outputs[0].value.storyboards[0].firstFramePrompt

引用对所有 flag 都生效（prompt、url、id 都可以）。--dry-run 可以查看引用替换后的 input，不真正调用 API。

本地文件与 Data URL

媒体字段（--image、--video、--audio 等）支持三种值：

• https://... —— 原样传入
• data:image/png;base64,... —— 自动上传到对象存储后替换为公开 URL
• ./path/to/file.png —— 自动上传到对象存储后替换为公开 URL

dlazy gpt-image-2 --image ./hero.png --prompt "油画风格"

文件大于 100 MB 会有警告日志；大于 500 MB 会被直接拒绝。

批量生成

所有生成类工具（image / video / audio / text / auto）都支持 --batch <n>，CLI 会用同一份输入并行执行 N 次，并把每次的 outputs 合并到同一个信封：

# 一次出 4 张图（并行），合并到 outputs[0..3]
dlazy gpt-image-2 --prompt "雨夜赛博朋克猫" --batch 4

# 配合管道引用：4 张图直接喂给下一个工具
dlazy gpt-image-2 --prompt "..." --batch 4 \
  | dlazy veo-3.1 --image @0.url --prompt "镜头推进"

usage.creditsCost / tokenIn / tokenOut 会跨子任务求和；durationMs 取并行墙钟（最大值）。配合 --no-wait 时，每个子任务的 task 会以 json 类型 output 的形式落到 outputs 数组里，方便下游管道继续读取所有 generateId。

异步任务

视频类工具大多是异步任务，CLI 默认会轮询直到完成。手动控制：

dlazy veo-3.1 --image hero.png --no-wait                  # 立即返回 generateId
dlazy status gen_abc123 --wait --tool veo-3.1             # 阻塞直到完成（按工具的 outputSchema 解析）
dlazy status gen_abc123                                    # 单次查询

--timeout <seconds> 控制轮询超时（默认 30 分钟）。status 命令传 --tool <cli_name> 可按对应工具的 outputSchema 解析结果；不传则按原始 JSON 输出。

工具发现

dlazy <tool> --help            # 该工具所有参数 / 默认值 / 依赖关系
dlazy tools list               # 注册表概览
dlazy tools describe <tool>    # 完整 input / output JSON Schema

CLI 会把 manifest 缓存到 ~/.dlazy/manifest-<locale>.json，TTL 24 小时，并在后台静默刷新。这样 --help 在弱网 / 离线下依然秒开。

ToolResult —— 统一输出契约

CLI 在 stdout 把结果包成 { ok: true, result }：

type ToolResult = {
  tool: string // cli_name，如 "seedream-4.5"
  modelId: string // 服务端模型 id
  outputs: Output[] // 始终是数组，永远不是标量
  usage?: {
    creditsCost?: number
    durationMs?: number
    tokenIn?: number
    tokenOut?: number
  }
  task?: {
    // wait=false 或异步任务时存在
    generateId: string
    status: 'pending' | 'running'
  }
}

CLI 默认 --format json 的成功信封：

{
  "ok": true,
  "result": {
    "tool": "gpt-image-2",
    "modelId": "gpt-image-2",
    "outputs": [
      {
        "type": "image",
        "id": "o_8a1f3b7d",
        "url": "https://cdn.dlazy.com/...png",
        "mimeType": "image/png"
      }
    ]
  }
}

失败信封：

{ "ok": false, "code": "insufficient_balance", "message": "...", "details": {} }

退出码：成功 0；运行时 / 网络错误 1；输入 / 配置错误 2（缺字段、JSON 解析失败、未知工具、引用错误等）。

支持的工具

下表为快照，请用 dlazy tools list 查看实时注册表，用 dlazy tools describe <name> 查看完整 schema。

运行环境

• Node.js ≥ 18（构建目标 node18，依赖 fetch 和异步迭代器）。
• CLI 打包为单个 CJS bundle。