> ## Documentation Index > Fetch the complete documentation index at: https://docs.dreamlayer.io/llms.txt > Use this file to discover all available pages before exploring further. # DreamLayer CLI > Generate and edit images from your terminal, over local files, with one API key. # 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 back to disk, so it composes with the tools you already use. ## 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](https://nodejs.org) * A DreamLayer API key with credits ## Steps ### 1. Install ```bash theme={null} npm install -g dreamlayer ``` ### 2. Give it the key ```bash theme={null} 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](/mcp), so there is one credential and one balance to track. ### 3. Generate ```bash theme={null} dreamlayer generate "A glass greenhouse at dusk" --aspect 1:1 --out greenhouse.png ``` ### 4. Edit from a reference image ```bash theme={null} dreamlayer edit photo.png "make it night, keep the composition" --out night.png ``` ### 5. Cut out the background ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} 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 ` 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 * [Connect an MCP client](/mcp) * [Read the endpoint reference](/agent-api) * [Make retries safe](/agent-api/idempotency-and-retries)