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 alongside the official SDKs.

Install

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

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

imagen --version

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:

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

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

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

Global options

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

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:

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

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

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:

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.

A minimal agent recipe

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

# 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