# Layer CLI

> Generate images, video, 3D, and audio with 300+ models from a terminal. One command, scriptable output, documented exit codes.

Install: `uv tool install layer` or `pipx install layer` or `pip install layer`
Package: `layer` on PyPI (https://pypi.org/project/layer/), Python 3.10 or newer
Authentication: `layer login` (browser), `layer login --device` (no browser), or `LAYER_API_KEY` set to a personal access token for CI.

## Quickstart

- `uv tool install layer` — Install. One self-contained tool, on any Python 3.10 or newer.
- `layer login` — Sign in. Opens a browser and stores the credential in your OS keychain. Use --device over SSH.
- `layer generate image -p "a cyberpunk market stall, isometric"` — Generate. Picks the recommended model, prices the run, waits for it, and writes the file to your working directory.

## Commands

- **Sign in** — layer login, logout, whoami, and use — browser sign-in, a device code for headless machines, or LAYER_API_KEY for CI.
- **Generate** — layer generate image, video, mesh, and audio, plus generate status for a run you submitted with --no-wait.
- **Models** — layer base-models list and show — what your workspace can run, and exactly what each model accepts.
- **Configuration** — Named profiles, a committed layer.toml that pins a checkout to its workspace, and the environment variables that override both.

## Generation flags

- **-p, --prompt** — what to generate; `-n` makes up to 16 at once.
- **--base-model** — which model to run. Omitted, the CLI picks the recommended one and prints its choice.
- **--aspect-ratio, --resolution, -d/--duration** — output shape, size, and length. A flag the modality does not understand is refused rather than dropped.
- **--param key=value** — a model-specific setting, validated against that model's inference schema before the request is sent.
- **--reference-set** — apply a trained style or reference set. Repeatable.
- **--confirm, --max-cost** — prompt before spending, or refuse a run over a Creative Unit ceiling. The estimate is printed either way.
- **--no-wait** — submit and print the id; read it back with `layer generate status <id> --wait`.
- **-o, --no-download** — where to write the result, or print URLs instead. Files never overwrite an existing name.

## Examples

- Image: `layer generate image -n 4 -p "crystal sword icon, transparent background"`
- Video: `layer generate video -d 5 --aspect-ratio 16:9 -p "camera pushes through the gate"`
- 3D: `layer generate mesh -p "weathered treasure chest, game-ready" -o props/`
- Audio: `for s in hit crit block; do layer generate audio -p "$s sfx, arcade" -o sfx/; done`
- Scripting: `id=$(layer --json generate video --no-wait -p "..." | jq -r .inference_id)`

## Configuration

Settings resolve in this order, highest first. A committed `layer.toml` pins a checkout to its workspace and project, so two repos open in two terminals cannot generate into each other's.

- A command-line flag — --profile, --workspace, --project, --api-url
- An environment variable — LAYER_PROFILE, LAYER_WORKSPACE, LAYER_PROJECT, LAYER_API_URL, LAYER_API_KEY
- layer.toml, found by walking up from the working directory
- The active profile in ~/.layer/config.toml

## Scripting

`--json` puts the result on stdout and nothing else; progress, warnings, and errors all go to stderr, so a pipeline never has to filter them out. `--quiet` suppresses stderr progress. Exit codes are part of the published contract and may gain members but never change meaning.

- `0` OK — The run finished.
- `1` ERROR — Anything without a more specific code.
- `2` USAGE — Unknown flag, missing argument, or a bad value.
- `3` AUTH — Not signed in, expired, or the token lacks access.
- `4` INSUFFICIENT_BALANCE — The workspace cannot pay for the run.
- `5` INVALID_INPUT — The API rejected the request as invalid.
- `6` CONTENT_POLICY — Refused by the content policy.
- `7` TIMEOUT — The run did not finish inside the time allowed.

## Billing

Generations consume Creative Units from your workspace balance, exactly as in the Layer app. There is no separate CLI charge and no extra per-seat cost. Every run prints its estimate before it spends anything.

Pricing: https://layer.ai/pricing

## Links

- CLI landing page: https://layer.ai/cli
- CLI docs: https://layer.ai/docs/cli
- PyPI: https://pypi.org/project/layer/
- Models: https://layer.ai/models
- MCP server, for an agent rather than a script: https://layer.ai/mcp
- Agent Skills: https://layer.ai/skills
- REST API: https://layer.ai/docs