---
title: "Imagen CLI for terminals and AI agents"
description: "Install and use the Imagen CLI: a single self-contained binary that edits photos from the terminal, with JSON output and exit codes built for AI agents."
canonical: https://api-docs.imagen-ai.com/docs/cli/
last-updated: 2026-08-27
---

# Imagen CLI for terminals and AI agents

The `imagen` CLI is a standalone command-line tool that wraps the full Imagen API. It ships as a single self-contained binary - **no Python or other runtime required** - and is built to be driven by both humans and AI agents: every command supports `--json`, uses stable exit codes, and never prompts interactively.

Use it when you want to edit photos from the terminal, wire Imagen into a shell script or CI job, or let an AI agent run your editing workflow without writing any SDK code. The CLI lives in the [imagen-ai-sdk repository](https://github.com/imagenai/imagen-ai-sdk) alongside the official SDKs.

## Install

One command on macOS (Apple Silicon) and Linux (x64 and arm64):

```curl
curl -fsSL https://raw.githubusercontent.com/imagenai/imagen-ai-sdk/master/sdks/python/packaging/install.sh | sh
```

The installer downloads the right binary for your platform into `~/.local/bin`. On Windows, download `imagen-windows-x64.exe` from the [latest release](https://github.com/imagenai/imagen-ai-sdk/releases/latest). Intel Macs have no prebuilt binary - install from source instead with `pip install imagen-ai-sdk`, which provides the same `imagen` command.

Verify the install:

```curl
imagen --version
```

> **Already using the Python SDK?** `pip install imagen-ai-sdk` also installs the `imagen` command, so if you have the Python SDK you already have the CLI.

## Authentication

The CLI looks for your API key in this order:

1. `--api-key <key>` flag on the command line
2. `IMAGEN_API_KEY` environment variable
3. `~/.imagen/config.json`, written by `imagen config`

Set it once and forget it:

```curl
imagen config --api-key YOUR_API_KEY
imagen config --profile 328        # optional: a default editing profile
imagen config                      # show current config (key is masked)
```

Don't have an API key yet? See [Onboarding](/docs/onboarding) for how to get one.

## Edit photos

The `edit` command runs the entire workflow in one call: it creates a project, uploads your photos, starts editing with your chosen AI Profile, waits for completion, and downloads the results.

```curl
# 1. Find a profile key
imagen profiles

# 2. Edit a folder of RAW files with profile 328, as a wedding, with crop and skin smoothing
imagen edit ./raws --profile 328 --type wedding --crop --smooth-skin --out ./edited

# Also export final JPEGs
imagen edit ./raws --profile 328 --export
```

`edit` accepts a folder or a single file. Results download by default; pass `--no-download` to skip.

### Editing options

Each flag maps 1:1 to an [AI tool in the API](/docs/ai-tools). Only pass the flags you want enabled - unset flags are left untouched, not forced off.

`--crop` - `--straighten` - `--hdr-merge` - `--portrait-crop` - `--smooth-skin` - `--subject-mask` - `--headshot-crop` - `--perspective-correction` - `--sky-replacement` - `--sky-template-id N` - `--window-pull` - `--crop-aspect-ratio 2X3|4X5|5X7`

### Photography types

Pass `--type` with one of: `no_type`, `other`, `portraits`, `wedding`, `real_estate`, `landscape_nature`, `events`, `family_newborn`, `boudoir`, `sports`, `school` (case-insensitive). Choosing the right type improves AI quality.

### File-type rules

> **RAW and JPEG cannot be mixed in one project** If a folder contains both, `edit` fails. Run RAW-only and JPEG-only folders separately, each with a matching profile - RAW profiles can't process JPEGs and vice versa.

- Only the **top level** of the folder is scanned; subfolders (for example a previous `edited/` output) are ignored.
- Supported RAW extensions: `.dng .nef .cr2 .arw .nrw .crw .srf .sr2 .orf .raw .rw2 .raf .ptx .pef .rwl .srw .cr3 .3fr .fff`
- Supported JPEG extensions: `.jpg .jpeg`. Other formats (HEIC and so on) are skipped.

## Command reference

Run `imagen --help` or `imagen <command> --help` at any time - the CLI is self-documenting, and new capabilities appear there automatically.

| Command | What it does |
| ------------------------------------------- | ----------------------------------------------------------- |
| `imagen profiles` | List your editing profiles (each has a `profile_key`) |
| `imagen projects` | List projects in your account (`--size`, `--page`) |
| `imagen edit FOLDER --profile K` | Full workflow: create project, upload, edit, download |
| `imagen enhance PROJECT FILE --tool-id T` | Apply an AI quick tool to an already-edited image |
| `imagen i2i FOLDER` | Run the [image-to-image](/docs/reference/smart-editing) workflow |
| `imagen sky-templates` | List sky-replacement template ids |
| `imagen ai-tools PROJECT` | List AI quick tools available for a project |
| `imagen config` | Show or set persisted defaults |
| `imagen skill` | Print or install the agent skill (`--claude` / `--codex`, `--install`) |

### Global options

Global options go **before** the command, for example `imagen --json profiles`.

| Option | Meaning |
| ---------------- | ---------------------------------------------------- |
| `--json` | Emit a single machine-readable JSON document on stdout |
| `--api-key TEXT` | Override the API key for this invocation |
| `--base-url TEXT`| Override the API base URL |
| `-V, --version` | Print the version |

## Scripting with JSON output and exit codes

Add `--json` to get a single JSON document on stdout. On failure, the CLI prints `{"error": "...", "message": "..."}` on **stderr** and returns a non-zero exit code:

| Exit code | Meaning |
| --------- | ----------------------------------------------------------------------------- |
| `0` | Success |
| `2` | Authentication or configuration problem (missing or invalid key, missing profile) |
| `1` | Any other failure (API error, bad input, mixed RAW and JPEG, and so on) |

```curl
imagen --json profiles | jq '.[0].profile_key'
```

```curl
# success JSON goes to stdout, error JSON goes to stderr - capture both
if imagen --json edit ./raws --profile 328 > result.json 2> error.json; then
  jq -r '.downloaded_files[]' result.json
else
  jq -r '.message' error.json >&2
fi
```

That's all a script or CI job needs - no SDK import required.

## For AI agents

The CLI is designed to be operated by coding agents such as Claude Code. If you are an agent (or you're setting one up), these four rules are all you need:

1. **Always pass `--json`** for anything you parse. Output is a single JSON document on stdout; the human-readable tables are only for interactive use.
2. **Check the exit code**: `0` success, `2` auth or config problem, `1` any other failure. In `--json` mode, failure details are printed as JSON on stderr.
3. **Discover, don't guess.** Run `imagen --help` and `imagen <command> --help` to see every command and flag - the help output is the source of truth, and new capabilities appear there automatically.
4. **Never invent flags.** If unsure, read `--help`.

### Install the agent skill

The CLI ships an installable skill that teaches agents these rules plus the full workflow - including the RAW/JPEG rules and photography types above. The skill text is embedded in the binary, so the CLI is self-bootstrapping - no repo checkout needed:

```curl
imagen skill --claude --install    # -> ~/.claude/skills/imagen-cli/SKILL.md
imagen skill --codex --install     # -> ~/.codex/skills/imagen-cli/SKILL.md
imagen skill                       # print the skill text to stdout
imagen --json skill                # {"format": "...", "content": "..."} (--json is global, goes first)
```

`--claude` and `--codex` only pick the install location; the skill content is identical. With the skill installed, prompts like "edit the RAW files in `~/shoots/smith-wedding` with my wedding profile" work out of the box: the agent installs the CLI if needed, finds a profile key, runs `edit`, and reports the downloaded files.

If the CLI isn't installed yet, you can also fetch the skill straight from the repository:

```curl
mkdir -p ~/.claude/skills/imagen-cli
curl -fsSL https://raw.githubusercontent.com/imagenai/imagen-ai-sdk/master/skills/imagen-cli/SKILL.md \
  -o ~/.claude/skills/imagen-cli/SKILL.md
```

For other agent frameworks, pipe `imagen skill` into the agent's context, or point it at [`skills/imagen-cli/SKILL.md`](https://github.com/imagenai/imagen-ai-sdk/blob/master/skills/imagen-cli/SKILL.md).

### A minimal agent recipe

An agent driving the CLI needs nothing beyond shell access and an API key:

```curl
# make sure the CLI is available
# (the installer fails by design on Intel macOS - fall back to: pip install imagen-ai-sdk)
imagen --version || curl -fsSL https://raw.githubusercontent.com/imagenai/imagen-ai-sdk/master/sdks/python/packaging/install.sh | sh

# authenticate (or rely on IMAGEN_API_KEY in the environment)
imagen config --api-key "$IMAGEN_API_KEY"

# discover profiles, then edit
imagen --json profiles
imagen --json edit ./raws --profile 328 --type wedding --crop
```

> **Long-running edits** `edit` blocks until editing completes, which can take a while for large projects. Agents should run it in the foreground so progress is visible, rather than burying it in a background task.