# CLI

Install the Lets Gen CLI and use the API from your terminal or coding agent.

The [Lets Gen CLI](https://github.com/LetsGenLab/letsgen-cli) is a standalone executable named `letsgen`. Discover models, upload owned references, generate image/video/audio, recover requests, and download completed outputs. Use the HTTP API for [text streaming](/docs/api/text) and [video analysis](/docs/api/extract), which are not CLI commands yet.

## Install

Find packaged executables and checksum-verified installers on the [GitHub releases page](https://github.com/LetsGenLab/letsgen-cli/releases). Supported targets are macOS, Linux, and Windows on x86-64 and arm64. If a packaged release is not available yet, install from source with Go 1.25 or later:

```bash
go install github.com/LetsGenLab/letsgen-cli/cmd/letsgen@v0.1.0-alpha.1
letsgen version
```

Add Go's binary installation directory to your `PATH` if `letsgen` is not found. Follow the repository's [installation guide](https://github.com/LetsGenLab/letsgen-cli#install) for packaged installation and upgrades.

## Sign in

Use this API base URL for sign-in and subsequent commands.

```bash
letsgen --origin https://letsgen.app auth login
letsgen --origin https://letsgen.app auth status
```

Browser login creates a revocable 30-day personal key. Choose read-only access with `--read-only` or set `--monthly-gem-cap N`; a cap of `0` disables spending. `--no-browser` prints the sign-in URL, but the browser must still reach the terminal's loopback callback. For remote terminals, use `auth login --api-key` and enter the key at its hidden prompt. Never put credentials in command arguments or chat.

For automation, provide `LETSGEN_API_KEY` securely in the environment; it overrides saved credentials. Set `LETSGEN_API_ORIGIN=https://letsgen.app` to avoid repeating `--origin`. `LETSGEN_CONFIG_DIR` selects a different credential/request storage directory.

## Discover, preview, then generate

```bash
letsgen --origin https://letsgen.app --json models list --kind image
letsgen --origin https://letsgen.app models inspect MODEL_ID

# Preview only: no network calls, uploads, or Gem spending.
letsgen --origin https://letsgen.app --json generate image \
  --model MODEL_ID --prompt 'A red fox in the snow' --max-gems 10 --dry-run

# Run only after approving this request's Gem budget.
letsgen --origin https://letsgen.app generate image \
  --model MODEL_ID --prompt 'A red fox in the snow' --max-gems 10 --output ./out
```

Replace `MODEL_ID` with a current catalog ID. `baseGems` is not an exact quote. Pass only supported model settings in `--parameters`, for example `'{"ratio":"1:1"}'`. Repeat `--reference ASSET_ID` for owned references after `assets upload FILE`.

Use `generate video` for video, or `generate audio --operation speech|music|voice_clone` for audio. Speech and voice cloning need an authorized `voiceProfileId` in parameters; discover voices with `voices list --scope mine`. See [image](/docs/api/image), [video](/docs/api/video), and [audio](/docs/api/audio) for input limits.

## Tasks and request recovery

Generation waits up to 10 minutes by default. `--timeout 20m` changes the wait; `--async` returns the durable task immediately. A timeout does not cancel the server task.

```bash
letsgen --origin https://letsgen.app tasks get TASK_ID
letsgen --origin https://letsgen.app tasks wait TASK_ID --timeout 10m
letsgen --origin https://letsgen.app tasks download TASK_ID --output ./out

# Recover an uncertain submission with its saved identity and exact payload.
letsgen --origin https://letsgen.app requests list
letsgen --origin https://letsgen.app requests retry REQUEST_ID --async
```

Retry with the original origin and credential. Never create another request to recover an ambiguous submission. Downloads refresh signed URLs and never generate again or overwrite existing files. Partial tasks may still contain successful outputs.

## Coding agents and scripts

`--json` keeps stdout machine-readable; progress and errors go to stderr. Agents need explicit spending permission and a numeric Gem budget before generation, with `--max-gems` on every approved request. A per-request ceiling does not replace a total session budget.

The CLI bundles its own `letsgen` skill:

```bash
letsgen skills list
letsgen skills show
letsgen skills install --target codex
letsgen skills install --target claude
```

These install under `~/.codex/skills/letsgen` or `~/.claude/skills/letsgen`. Choose another skill root with `--path DIR`; existing skills are not overwritten. The docs-hosted [generation skill](/docs/agents) also links to this CLI guide and the HTTP reference.

Exit codes: `0` success, `1` request/local failure, `2` invalid usage, `3` authentication/access, `4` timeout/interruption, `5` failed task/no outputs. Use `letsgen help` for the complete command list.

## Sign out

```bash
letsgen --origin https://letsgen.app auth logout
```

Logout revokes the saved credential and removes it locally. Remove any separately supplied environment credential from your shell or secret manager as needed.