@dlazy/cli

English · 中文

Generate images, videos, speech, and music from your terminal — and chain AI tools together with ordinary shell pipes.

dlazy puts every model on dLazy behind one consistent command shape. Every command prints the same structured ToolResult JSON envelope to stdout, so one tool's output flows straight into the next:

dlazy gpt-image-2 --prompt "a cyberpunk cat in neon rain" \
  | dlazy veo-3.1 --image - --prompt "drone push-in, rainy night"

Human-readable progress always goes to stderr, so stdout stays clean, scriptable JSON.

Quick start

Three steps to your first image — all you need is Node.js ≥ 18.

1 · Install

npm install -g @dlazy/cli

2 · Log in (opens your browser, saves the key to ~/.dlazy/config.json)

dlazy login

3 · Generate

dlazy gpt-image-2 --prompt "a cyberpunk cat in neon rain" --save cat.png

That's it — cat.png is on your disk. 🎉 Run dlazy tools list to see everything else you can do.

What can it do?

You want to…	Try these tools
🖼️ Create & edit images	`gpt-image-2`, `seedream-4.5`, `banana2`, `mj-imagine`, …
🎬 Turn text or images into video	`veo-3.1`, `seedance-2.0`, `kling-v3`, `wan2.7`, …
🔊 Speech, sound effects & music	`gemini-2.5-tts`, `keling-sfx`, `suno-music`, …
📝 Storyboards & workflow plans	`script`, `plan`, `execute`
🧰 Glue tools into pipelines	pipe any command into the next with `\|`

The full catalog lives in Supported tools — or run dlazy tools list for the live registry.

Install

# Global (adds `dlazy` to PATH)
npm install -g @dlazy/cli

# Project-local (run via `npx dlazy ...`)
npm install @dlazy/cli
# or: pnpm add @dlazy/cli   |   yarn add @dlazy/cli

Log in

dlazy login                 # device-code flow; opens browser, saves key to ~/.dlazy/config.json
dlazy login --local         # use http://localhost:3000 for local server testing
dlazy auth set sk-xxxx      # set key directly
dlazy auth get              # show current key (masked)
dlazy auth get --show       # reveal full key
dlazy logout                # clear key from config

Resolution order at runtime: --api-key flag → DLAZY_API_KEY env → ~/.dlazy/config.json → interactive login (TTY only).

Everyday recipes

Save a result straight to disk — --save downloads the asset, creates the folder, and retries for you:

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

Image → video, in one line:

dlazy gpt-image-2 --prompt "detective profile" \
  | dlazy veo-3.1 --image - --prompt "drone push-in, rainy night"

Four variants at once, then pick the 2nd for video:

dlazy gpt-image-2 --batch 4 --prompt "..." \
  | dlazy veo-3.1 --image @1.url --prompt "slow zoom"

Pull fields out with jq — stdout is always one JSON envelope:

# storyboard markdown out of the `script` tool
dlazy script --prompt "6 cinematic shots about a stray cat" \
  | jq -r '.result.outputs[0].value.texts[0]' > script.md

# grab the image URL, or the error message if it failed
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'

Submit now, collect later (async tools):

dlazy veo-3.1 --image hero.png --prompt "..." --no-wait   # returns generateId
dlazy status gen_abc123 --wait

Preview without spending anything — --dry-run resolves references and echoes the payload with no auth, upload, or network call:

dlazy gpt-image-2 --prompt "..." --dry-run

List tools / inspect one:

dlazy tools list
dlazy tools describe gpt-image-2

Flags & options

Global flags

Flag	Effect
`--api-key <key>`	Override stored API key for this run
`--base-url <url>`	Override server (default: `DLAZY_BASE_URL` or `https://dlazy.com`)
`--verbose`	Debug logs to stderr
`--format <mode>`	stdout format — `json` (default) / `url` / `text`
`-l, --lang <locale>`	UI / help language: `en-US` or `zh-CN`

Locale is also picked up from DLAZY_LANG, then LC_ALL, then LANG.

Per-run flags (every tool command)

Flag	Effect
`--dry-run`	Resolve refs and echo the payload without auth, upload, or any network call
`--no-wait`	For async tools: return `{ generateId, status }` immediately
`--timeout <seconds>`	Polling deadline for async completion (default 1800)
`--input <jsonOrFile>`	Inline JSON object or `@path/to/file.json`; merged under flag values (flags win)
`--save <path>`	Download the result asset to this local path (mkdir + retry handled for you)
`--batch <n>`	Run the tool N times in parallel and merge all outputs (image/video/audio/text/auto)

Output modes (`--format`)

stderr always carries human-readable progress; stdout is the machine-readable channel.

Mode	stdout
`json` (default)	Full envelope `{ ok, result }` (or `{ ok: false, code, message }`)
`url`	One URL per line (only media outputs)
`text`	One text block per output (only text outputs)

See Everyday recipes for jq one-liners that pick fields out of the default JSON envelope.

Pipes & reference tokens

When you pipe one dlazy command into another, the second command can read the first one's stdout envelope. In any flag value, a reference token says which part of that envelope to use. References are resolved before any network call, so you compose tools without writing JSON paths into shell variables.

Token	Meaning
`-`	Auto-pick — first output's primary value (scalar field) or all primary values (array field)
`@<n>`	n-th output's primary value (`@0` = first)
`@<n>.<path>`	jsonpath into the n-th output (e.g. `@0.url`, `@1.meta.fps`, `@0.text`)
`@*`	All outputs as an array of primary values
`@stdin`	The entire piped envelope
`@stdin:<path>`	jsonpath into the entire envelope (e.g. `@stdin:result.usage.creditsCost`)

Examples:

# 1) Single image → video (auto-resolution)
dlazy gpt-image-2 --prompt "..." \
  | dlazy veo-3.1 --image - --prompt "drone shot"

# 2) Pick the 2nd image from a 4-up batch
dlazy gpt-image-2 --batch 4 --prompt "..." \
  | dlazy veo-3.1 --image @1.url --prompt "slow zoom"

# 3) Array field: upstream's URLs flatten in
dlazy gpt-image-2 --batch 4 --prompt "..." \
  | dlazy merge --videos -

# 4) Storyboard text from `script` drives the next prompt
dlazy script --prompt "6 cinematic shots about a stray cat" \
  | dlazy gpt-image-2 --prompt @stdin:result.outputs[0].value.storyboards[0].firstFramePrompt

References work for any flag — text prompts, urls, ids, anything. --dry-run shows the resolved input without calling the API.

Local files & data URLs

Any media-typed flag accepts:

https://... — passed through
data:image/png;base64,... — uploaded to object storage, replaced with a public URL
./path/to/file.png — uploaded to object storage, replaced with a public URL

dlazy gpt-image-2 --image ./hero.png --prompt "stylize as oil painting"

Files larger than 100 MB log a warning; files larger than 500 MB are rejected.

Batch generation

All generation tools (image / video / audio / text / auto) accept --batch <n>. The CLI runs the tool N times in parallel with the same input and merges every run's outputs into one envelope:

# 4 image variants in one call (parallel) — outputs[0..3]
dlazy gpt-image-2 --prompt "rainy-night cyberpunk cat" --batch 4

# Combine with pipe references — feed each variant into a single video
dlazy gpt-image-2 --prompt "..." --batch 4 \
  | dlazy veo-3.1 --image @0.url --prompt "push-in"

usage.creditsCost / tokenIn / tokenOut are summed across runs; durationMs reports parallel wallclock (max). With --no-wait, each sub-run's task is surfaced as a JSON output so downstream pipes can still read every generateId.

Async tasks

Long-running tools (most video models) return a generateId and the CLI polls until completion by default. Override:

dlazy veo-3.1 --image hero.png --no-wait              # return generateId immediately
dlazy status gen_abc123 --wait --tool veo-3.1         # block until done (typed by tool's outputSchema)
dlazy status gen_abc123                                # one-shot status check

--timeout <seconds> controls the polling deadline (default 30 min). Pass --tool <cli_name> on status to parse the result through that tool's outputSchema; without it, the result comes back as a raw JSON output.

Finding tools

dlazy <tool> --help            # all flags + types + defaults + dependent options
dlazy tools list               # registry overview
dlazy tools describe <tool>    # full input / output JSON Schema

The CLI caches the manifest for 24 h under ~/.dlazy/manifest-<locale>.json and refreshes it in the background, so --help stays fast offline.

Optional local runtimes

A few local tools (video_compose --render_runtime remotion, video_downloader) need extra binaries. Install on demand:

dlazy doctor remotion --install                     # React/spring render path
dlazy doctor yt-dlp --install [--proxy http://...]  # reference-video downloads

Render runtimes supported by video_compose:

Runtime	State	How to enable
`ffmpeg`	✓ ready	Install `ffmpeg` on your system, or set `DLAZY_FFMPEG_PATH` when it lives outside `PATH`.
`remotion`	⚙ installable	`dlazy doctor remotion --install` (~50s, 195 packages). Then `render_runtime: "remotion"` uses 5 built-in scenes — `hero_title`, `text_card`, `stat_card`, `callout`, `bar_chart`. See `runtime/remotion-composer/SCENE_TYPES.md`.
`hyperframes`	✗ not yet shipped	Not implemented in `video_compose`; pick `ffmpeg` or `remotion`.

ToolResult — the unified output contract

The CLI wraps this shape as { ok: true, result } on stdout.

type ToolResult = {
  tool: string // cli_name, e.g. "seedream-4.5"
  modelId: string // server-side model id
  outputs: Output[] // always an array, never a scalar
  usage?: {
    creditsCost?: number
    durationMs?: number
    tokenIn?: number
    tokenOut?: number
  }
  task?: {
    // present when wait=false / async
    generateId: string
    status: 'pending' | 'running'
  }
}

Sample envelope (CLI default --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"
      }
    ]
  }
}

Failure envelope:

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

Exit codes: 0 on success, 1 for runtime / network failures, 2 for input / config errors (missing field, bad JSON, unknown tool, bad ref).

Supported tools

A snapshot — run dlazy tools list to see the live registry, or dlazy tools describe <name> for full input/output schemas.

Command	Type	Description
`seedream-4.5`	image	Doubao Seedream 4.5 high-quality text-to-image / reference-to-image.
`seedream-5.0-lite`	image	Doubao Seedream 5.0 fast image generation.
`banana2` / `banana-pro`	image	Gemini Banana general / pro text-to-image.
`gpt-image-2`	image	GPT Image 2 (text + reference image editing).
`grok-4.2`	image	Minimal text-to-image.
`recraft-v3` / `recraft-v3-svg` / `recraft-v4*`	image	Stylized / vector / pro variants.
`kling-image-o1`	image	Kling image (multi-image constraints).
`mj-imagine`	image	Midjourney-style.
`viduq2-t2i` / `jimeng-t2i`	image	Vidu / Jimeng text-to-image.
`imageseg` / `superres`	tool	Background removal / upscale.
`veo-3.1` / `veo-3.1-fast`	video	Veo high-quality / fast text-to-video.
`seedance-2.0` / `seedance-2.0-fast` / `seedance-1.5-pro`	video	ByteDance Seedance video.
`kling-v3` / `kling-v3-omni`	video	Kling V3 / omni-control video.
`wan2.6-r2v` / `wan2.6-r2v-flash` / `wan2.7`	video	Tongyi Wanxiang video.
`pixverse-c1`	video	PixVerse C1 (action / VFX).
`viduq2-i2v`	video	Vidu image-to-video.
`jimeng-i2v-first` / `jimeng-i2v-first-tail` / `jimeng-dream-actor` / `jimeng-omnihuman-1.5`	video	Jimeng video family.
`video-replicate` / `image-replicate`	video / image	Replicate-bridged models.
`video-scenes` / `merge`	video	Scene split / multi-clip merge.
`gemini-2.5-tts`	audio	Gemini 2.5 Pro TTS.
`keling-tts` / `doubao-tts`	audio	Kling / Doubao speech synthesis.
`keling-sfx`	audio	Sound effects / foley.
`suno-music`	audio	Suno music generation.
`vidu-audio-clone` / `kling-audio-clone`	audio	Voice cloning.
`plan` / `execute`	text	Workflow planning / execution.
`script`	text	Storyboard generator: structured subjects + storyboards from a free-text brief, with optional reference images.

Runtime requirements

Node.js ≥ 18 (built for node18 target; fetch and async iterators are required).
The CLI ships as a single CJS bundle.

Questions? Full documentation lives at https://dlazy.com/docs, and dlazy <tool> --help shows every flag with types and defaults.

Name		Name	Last commit message	Last commit date
.trae/rules		.trae/rules
bin		bin
scripts		scripts
skills		skills
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
frames.txt		frames.txt
gen-keyword-skills.cjs		gen-keyword-skills.cjs
package-lock.json		package-lock.json
package.json		package.json
publish-skills.ts		publish-skills.ts
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Navigation Menu

Uh oh!

Repository files navigation

@dlazy/cli

Contents

Quick start

What can it do?

Install

Log in

Everyday recipes

Flags & options

Global flags

Per-run flags (every tool command)

Output modes (`--format`)

Pipes & reference tokens

Local files & data URLs

Batch generation

Async tasks

Finding tools

Optional local runtimes

ToolResult — the unified output contract

Supported tools

Runtime requirements

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

@dlazy/cli

Contents

Quick start

What can it do?

Install

Log in

Everyday recipes

Flags & options

Global flags

Per-run flags (every tool command)

Output modes (--format)

Pipes & reference tokens

Local files & data URLs

Batch generation

Async tasks

Finding tools

Optional local runtimes

ToolResult — the unified output contract

Supported tools

Runtime requirements

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Output modes (`--format`)