DreamLayer CLI

What this lets you do

Run DreamLayer against files on your machine without writing an integration. The CLI reads local images, streams progress into your terminal, and writes finished PNGs or sprite ZIPs back to disk.

What you need

Node.js 22.12 or later. If you do not have it: brew install node on macOS, or the installer at nodejs.org
A DreamLayer API key with credits

Steps

1. Install

npm install -g dreamlayer

For sprite sheets, install the published beta instead:

npm install -g dreamlayer@0.4.0-beta.4

Both dreamlayer@beta and the pinned version above select 0.4.0-beta.4. The unversioned latest release remains 0.3.0. The beta includes existing image commands as well as sprite sheets. Installing it globally replaces your local CLI version; it does not change npm’s latest tag.

2. Give it the key

export DREAMLAYER_API_KEY="dlr_live_your_key_here"

The CLI reads the key from the environment. The same key works in your shell, in a build, and inside the MCP server, so there is one credential and one balance to track.

3. Generate

dreamlayer generate "A glass greenhouse at dusk" --aspect 1:1 --out greenhouse.png

4. Edit from a reference image

dreamlayer edit photo.png "make it night, keep the composition" --out night.png

5. Cut out the background

dreamlayer cutout product.png --out cutout.png

The result is a PNG with a real alpha channel, so it composites onto any background. Translucent subjects stay translucent: glass, smoke and hair keep their partial transparency rather than being forced solid.

6. Upscale

dreamlayer upscale photo.png --out large.png

Each side doubles. The input’s longest side must be 2048 or smaller, because 4096 is the delivery ceiling; an oversize request is refused before any provider is paid, not after. An upscaled image is therefore already at the maximum input dimension and cannot be upscaled a second time. Upscaling is the slowest operation, typically two to three minutes. The CLI waits as long as the server keeps the connection alive and only gives up if the stream goes silent, so a slow job is not mistaken for a dead one.

7. Check your balance without spending

dreamlayer balance

This reports promotional, purchased, and total available credits for the API key in DREAMLAYER_API_KEY. It calls no image service, costs nothing, and does not expose an account selector.

8. Check capabilities without spending

dreamlayer capabilities

This reports the protocol version, your key mode, and the operations your key can actually run. It calls no provider and costs nothing, which makes it the right first command after installing.

Confirm it worked

The command exits 0, the output file exists and opens as a PNG, and the Usage page in the console shows one settled credit.

Common errors

Error	What to do
`command not found`	The npm global bin directory is not on your PATH.
`EACCES` during global installation	Use a Node version manager, configure a user-owned npm prefix, or run `npx --yes dreamlayer …`. Do not install the CLI with `sudo`.
Exit code from an auth failure	`DREAMLAYER_API_KEY` is unset or revoked.
The run stops asking a question	The prompt was ambiguous. Answer it, or use an explicit subcommand so DreamLayer does not have to interpret.
Out of credits	Buy a pack on the Billing page. A new account starts at zero.
A command reports a stable error reason	Use the printed `reason`, `retryable`, and request ID. Retry only when `retryable` is true, and reuse the same idempotency key.
The stream went silent	The connection died, but the job may still be running and may already be charged. The message names the execution id: run `dreamlayer status <id>` to see how it ended. If you retry, pass the SAME `--idempotency-key` so it cannot be charged twice.
An upscale is refused before it starts	The input’s longest side is over 2048. Upscale doubles each side and 4096 is the ceiling, so this is refused at submit time rather than after a provider has been paid.

Troubleshooting

Every command accepts --json for machine-readable output. Error output carries only the stable public contract and excludes prompts, images, local filenames, and your key. Successful image output includes the destination path you selected, so remove that path before sharing it if the local name is private.

Next steps

Sprite-sheet beta

After setting your key, check access without generating anything:

npx --yes dreamlayer@0.4.0-beta.4 capabilities
npx --yes dreamlayer@0.4.0-beta.4 balance

This command starts a real, billable one-time animation:

npx --yes dreamlayer@0.4.0-beta.4 sprite ./chest.png \
  --animation-prompt 'Open the chest lid, revealing the contents, then hold it open.' \
  --animation-mode once --frames 7 --frame-size 512 \
  --max-credits 5.8 --out ./chest.zip

Use --animation-mode loop for repeating motion or a full turntable. Custom instructions default to once; presets default to loop. Use --action walk, run, or idle instead of --animation-prompt for a preset, never both. If neither is supplied, the CLI uses walk. Request 7–100 frames (default 12) and a square frame size of 32, 64, 128, 256, 512, 720, or 1080 (default 512). Approve the total rounded charge with --max-credits. New transparent sprites cost 5.6 credits for seven frames or 6.6 for twelve. Export size does not change pricing. Add --background keep when transparency is not needed: the frames keep the generated background. This costs $0.32 plus $0.01 per frame, converted to API credits at your account’s undiscounted purchase rate. A public twelve-frame request costs 2.9334 credits. That flag needs 0.4.0-beta.4 or later. The pinned older CLI still validates a historical spending ceiling locally. The 5.8-credit ceiling above is permission to spend at most that amount, not the new 5.6-credit charge. For exact current estimates, use the authenticated /v1/sprite-pricing endpoint. Do not treat the older client’s calculated minimum as today’s price. Keep your approved ceiling explicit. The frame-size response issue is fixed; 512 is the default, not a required workaround. Retrieve existing completed outputs using their original execution IDs without regenerating. Credits settle on complete delivery and are returned on failure or timeout. Sprite requests have no customer cancellation. Save the execution ID to resume status. See sprite sheets for output details and beta limitations.

Start

DreamLayer Agent API

Video

Command line and agents

Project

Endpoint reference

DreamLayer CLI

DreamLayer CLI

What this lets you do

What you need

Steps

1. Install

2. Give it the key

3. Generate

4. Edit from a reference image

5. Cut out the background

6. Upscale

7. Check your balance without spending

8. Check capabilities without spending

Confirm it worked

Common errors

Troubleshooting

Next steps

Sprite-sheet beta

​DreamLayer CLI

​What this lets you do

​What you need

​Steps

​1. Install

​2. Give it the key

​3. Generate

​4. Edit from a reference image

​5. Cut out the background

​6. Upscale

​7. Check your balance without spending

​8. Check capabilities without spending

​Confirm it worked

​Common errors

​Troubleshooting

​Next steps

​Sprite-sheet beta

DreamLayer CLI

What this lets you do

What you need

Steps

1. Install

2. Give it the key

3. Generate

4. Edit from a reference image

5. Cut out the background

6. Upscale

7. Check your balance without spending

8. Check capabilities without spending

Confirm it worked

Common errors

Troubleshooting

Next steps

Sprite-sheet beta