leonardo-cli
A Leonardo.Ai command-line interface for generating images, videos, upscales, and more.
Designed to be both AI-agent friendly (--json, deterministic exit codes, stderr logs) and human friendly (colors, progress, helpful errors).
$ leonardo generate "a cyberpunk cat" -o cat.png
→ Submitting generation (1024x1024, n=1)
generationId: 4f8e...
→ Polling for completion...
attempt 1 — status: PENDING
attempt 2 — status: COMPLETE
✓ Saved cat.png (812345 bytes)
done 1 image(s)
Install
Requires Bun ≥ 1.1.
git clone https://github.com/mrgoonie/leonardo-cli.git
cd leonardo-cli
bun install
# run from source
bun run leonardo --help
# or build a single executable
bun run build && ./dist/cli.js --help
After npm i -g leonardo-cli you get two binaries pointing to the same CLI:
leonardo — full nameleo — short alias
API Key
Get a key at https://app.leonardo.ai/api-access.
The CLI resolves your API key in this order — first match wins:
| Priority | Source | Example |
|---|
| 1 | --api-key flag | leonardo --api-key lk_… me |
| 2 | LEONARDO_API_KEY env var (incl. OS-level shell) | export LEONARDO_API_KEY=lk_… |
| 3 | .env.local / .env.*.local / .env (walks up from cwd) | see .env.example |
| 4 | ./leonardo.config.json (walks up from cwd) | see leonardo.config.example.json |
| 5 | User config: $XDG_CONFIG_HOME/leonardo-cli/config.json (default ~/.config/leonardo-cli/config.json) | written by leonardo config set |
Inspect what was resolved:
leonardo config path # paths + which source the key came from
leonardo config show # effective config (key redacted)
leonardo config set apiKey lk_xxx
Output
Single file:
leonardo generate "a sunset" -o sunset.png
Directory (auto-named: leonardo-<id>-NN.png):
leonardo generate "a sunset" -d ./outputs -n 4
Skip download (URLs only):
leonardo generate "a sunset" --no-download --json
Default output dir falls back to LEONARDO_OUTPUT_DIR env, then outputDir in config, then ..
Commands
| Command | Description |
|---|
generate <prompt> (gen) | Text-to-image with polling and download |
video <prompt> | Text-to-video (Motion / Veo / etc.) — returns a job id |
upscale <imageId> | Universal Upscaler |
variation <variationId> | Fetch upscale/variation result |
status <generationId> | Check status + image URLs |
models | List platform models (id\tname) |
me | Account info + remaining API credits |
config get/set/path/show | Manage config |
Run leonardo <command> --help for full options.
Generate options
-m, --model <id> Model UUID
-w, --width <n> Image width (default 1024)
-h, --height <n> Image height (default 1024)
-n, --num <n> Number of images
--alchemy Enable Alchemy
--ultra Enable Ultra mode
--contrast <n> Contrast (1.0-4.5)
--style <uuid> Style UUID
--seed <n> Seed
--negative <text> Negative prompt
--enhance Auto-enhance prompt
-o, --output <file> Output file (or directory)
-d, --output-dir <dir> Output directory
--no-download Skip downloading; print URLs only
--wait-timeout <ms> Polling timeout (default 480000)
AI-agent mode (--json)
Pass --json (or LEONARDO_JSON=1) to emit a single JSON object on stdout. All progress goes to stderr; colors are disabled.
$ leonardo generate "a cat" --json | jq '.images[0].path'
"./leonardo-4f8e0a2b-01.png"
Sample shape:
{
"ok": true,
"generationId": "4f8e0a2b-...",
"status": "COMPLETE",
"prompt": "a cat",
"model": "6b645e3a-d64f-4341-a6d8-7a3690fbf042",
"width": 1024,
"height": 1024,
"images": [
{ "id": "...", "url": "https://...", "path": "./leonardo-...-01.png", "bytes": 812345 }
]
}
Exit codes
| Code | Meaning |
|---|
| 0 | Success |
| 1 | Generic failure |
| 2 | Usage / argument error |
| 3 | Missing or invalid auth |
| 4 | Leonardo API error |
| 5 | Polling timeout |
Streams
stdout — JSON object (in --json mode), or primary data (URLs, IDs)stderr — human progress, warnings, errors
This separation lets you safely pipe stdout into jq / shell scripts without contaminating it.
Development
bun run dev <command> # run from source
bun run typecheck # tsc --noEmit
bun run build # produce dist/cli.js (single file)
Project layout:
ZenMux