> ## 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.

# CLI automation

> Machine-readable output, exit codes, noninteractive jobs, and recovery without duplicate work.

Requires version `0.4.0-beta.2` or later. Install this beta explicitly with `npm install -g dreamlayer@0.4.0-beta.3`.

The DreamLayer CLI never prompts interactively. Use explicit arguments, a server-side `DREAMLAYER_API_KEY`, and `--json` when consuming output in a script. Node.js 22.12 or later is required.

```bash theme={null}
dreamlayer --version
dreamlayer --help
dreamlayer capabilities --json
dreamlayer balance --json
```

Capabilities and balance do not start paid generation. Stable image commands install with `npm install -g dreamlayer`; sprite commands currently require the beta package described in the [CLI guide](/cli). Check the installed version before depending on a new command.

## Output and exit codes

Success JSON goes to stdout. API error JSON goes to stderr. Progress uses stderr and can be disabled with `--quiet`. Older versions can emit plain text for local validation and transport errors, so scripts must handle their installed version's contract.

| Exit | Meaning                                | Action                                                  |
| ---- | -------------------------------------- | ------------------------------------------------------- |
| 0    | Command succeeded                      | Inspect returned execution status for `status` commands |
| 1    | Usage or local failure                 | Check arguments, files, and configuration               |
| 2    | Authentication or account access       | Correct the key or access                               |
| 3    | Credits or quota                       | Resolve billing or quota before new work                |
| 4    | Permanent API failure or cancelled run | Inspect reason; fix the request                         |
| 5    | Temporary failure or incomplete run    | Check saved execution before retrying                   |
| 6    | Input required                         | Answer the question in its conversation                 |

A successful `status` read exits zero even when the execution itself failed. Branch on its JSON `status` too.

## Save request identity

For text-to-image, save your own unique key before running the command:

```bash theme={null}
dreamlayer generate "A glass greenhouse at dusk"   --idempotency-key greenhouse-001 --out greenhouse.png --json --quiet   > result.json 2> error.json
```

On uncertainty, read the saved execution:

```bash theme={null}
dreamlayer status EXECUTION_ID --json
```

Replaying text generation requires the same prompt, aspect ratio, and key. For commands that upload files (`edit`, `cutout`, `upscale`, `sprite`, and an answer with `--image`), invoking the command again uploads a new asset. Do not assume the same local filename produces byte-equivalent API requests. Recover the existing execution instead, or use the [journaled API examples](/agent-api/examples) to retain the original uploaded asset ID.

Before submission, generation commands reject existing output files, directories, and unavailable parent directories. Choose a new `--out` destination. If the destination becomes unavailable after submission, recover the existing execution rather than submitting again.

## Retrieve completed work

Run `dreamlayer download EXECUTION_ID --out recovered.png --json` to recover without a new submission. `local_output_failed` means the completed output could not be written: fix the destination and retry only the download. `download_failed` and `output_not_ready` also require recovery of existing work. A cancelled run reports `execution_cancelled` on stderr with exit 4.

Use the owned `download_url` in canonical state with an authenticated download as shown in [Assets](/agent-api/assets). Do not generate again to recover a missing local file. Never forward the API key to a redirected storage origin or put it in logs.

The client queue in [Process multiple images](/agent-api/multiple-images) preserves completed work and stops admission when a client failure leaves a job uncertain.