cli

install once, authenticate with email + OTP, and generate app-ready images straight from your terminal or coding agent.

install

install the cli globally with your package manager of choice.

shell

npm i -g @imaagine/cli

verify the install:

shell

imaagine --version
imaagine whoami

auth

authenticate interactively with email + OTP, or set the IMAAGINE_API_KEY environment variable for CI and agents.

shell

# interactive — email + OTP, stores CLI auth locally
imaagine login

# non-interactive — env var wins over stored auth
export IMAAGINE_API_KEY="imgn_abcd1234_sk_..."

stored credentials live at ~/.config/imaagine/config.json. remove them with imaagine logout.

json

// ~/.config/imaagine/config.json
{
  "auth": { "type": "email-otp" },
  "defaultModel": "basic",
  "baseUrl": "https://imaagine.app/api/v1"
}

commands

command	description
login	authenticate with email + OTP and store CLI auth locally
logout	remove the stored credentials
whoami	print the authenticated account and key prefix
usage	show available / reserved credits and recent spend
models	list model aliases, resolutions, and credit costs
generate	create an image from a prompt

generate flags

shell

imaagine generate "isometric server rack, blueprint style" \
  --out ./public/hero.png \
  --model basic --aspect 1:1 --resolution 1K

flag	arg	description
--out	<path>	write the image to a file in your repo
--url	—	return a public CDN url instead of a file
--model	<basic\|pro>	model alias · default basic
--aspect	<ratio>	1:1 · 16:9 · 9:16 · 4:3 · 3:4
--resolution	<res>	1K · 2K · 4K · default 1K
--json	—	emit a machine-readable json result on stdout
--idempotency-key	<key>	dedupe retries; same key returns the same image
--wait	—	block until the job completes (default)
--timeout	<ms>	max time to wait · default 60000
--force	—	overwrite an existing --out file
--mkdirs	—	create parent directories for --out

--out vs --url

choose how the result is delivered. you can combine both to get a public url and a local copy in one call.

invocation	behavior
--out ./public/hero.png	private image, written to disk; no public url minted
--url	public image, returns a permanent CDN url; nothing written
--url --out ./public/hero.png	public image, returns the url and also writes the file locally

json output

add --json for a structured result on stdout — ideal for scripts and agents.

json

{
  "image": {
    "id": "img_8fa20c",
    "status": "completed",
    "model": "basic",
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "width": 1024,
    "height": 1024,
    "visibility": "private",
    "path": "./public/hero.png",
    "public_url": null
  },
  "credits": { "charged": 3, "available": 42, "reserved": 0 }
}

exit codes

the cli maps API error codes to stable exit codes so scripts can branch deterministically.

code	meaning
0	success
1	generic / unexpected error
2	usage error (bad flags or arguments)
3	unauthorized (missing or invalid api key)
4	insufficient credits
5	moderation blocked
6	rate limited (retry after backoff)
7	provider unavailable (credits released)
8	generation failed

agent workflow

a typical coding-agent loop: generate with --json --out, parse the result, and branch on the exit code.

shell

#!/usr/bin/env bash
set -euo pipefail

result=$(imaagine generate "$PROMPT" \
  --out ./public/hero.png \
  --model basic --resolution 1K \
  --idempotency-key "$BUILD_ID" \
  --json) || code=$?

if [ "${code:-0}" -eq 4 ]; then
  echo "out of credits — see /pricing" >&2
  exit 4
fi

echo "$result" | jq -r '.image.path'

see the API docs → to call the same endpoints directly from a long-running agent.

cli

install once, authenticate with email + OTP, and generate app-ready images straight from your terminal or coding agent.

install

install the cli globally with your package manager of choice.

shell

npm i -g @imaagine/cli

verify the install:

shell

imaagine --version
imaagine whoami

auth

authenticate interactively with email + OTP, or set the IMAAGINE_API_KEY environment variable for CI and agents.

shell

# interactive — email + OTP, stores CLI auth locally
imaagine login

# non-interactive — env var wins over stored auth
export IMAAGINE_API_KEY="imgn_abcd1234_sk_..."

stored credentials live at ~/.config/imaagine/config.json. remove them with imaagine logout.

json

// ~/.config/imaagine/config.json
{
  "auth": { "type": "email-otp" },
  "defaultModel": "basic",
  "baseUrl": "https://imaagine.app/api/v1"
}

commands

command	description
login	authenticate with email + OTP and store CLI auth locally
logout	remove the stored credentials
whoami	print the authenticated account and key prefix
usage	show available / reserved credits and recent spend
models	list model aliases, resolutions, and credit costs
generate	create an image from a prompt

generate flags

shell

imaagine generate "isometric server rack, blueprint style" \
  --out ./public/hero.png \
  --model basic --aspect 1:1 --resolution 1K

flag	arg	description
--out	<path>	write the image to a file in your repo
--url	—	return a public CDN url instead of a file
--model	<basic\|pro>	model alias · default basic
--aspect	<ratio>	1:1 · 16:9 · 9:16 · 4:3 · 3:4
--resolution	<res>	1K · 2K · 4K · default 1K
--json	—	emit a machine-readable json result on stdout
--idempotency-key	<key>	dedupe retries; same key returns the same image
--wait	—	block until the job completes (default)
--timeout	<ms>	max time to wait · default 60000
--force	—	overwrite an existing --out file
--mkdirs	—	create parent directories for --out

--out vs --url

choose how the result is delivered. you can combine both to get a public url and a local copy in one call.

invocation	behavior
--out ./public/hero.png	private image, written to disk; no public url minted
--url	public image, returns a permanent CDN url; nothing written
--url --out ./public/hero.png	public image, returns the url and also writes the file locally

json output

add --json for a structured result on stdout — ideal for scripts and agents.

json

{
  "image": {
    "id": "img_8fa20c",
    "status": "completed",
    "model": "basic",
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "width": 1024,
    "height": 1024,
    "visibility": "private",
    "path": "./public/hero.png",
    "public_url": null
  },
  "credits": { "charged": 3, "available": 42, "reserved": 0 }
}

exit codes

the cli maps API error codes to stable exit codes so scripts can branch deterministically.

code	meaning
0	success
1	generic / unexpected error
2	usage error (bad flags or arguments)
3	unauthorized (missing or invalid api key)
4	insufficient credits
5	moderation blocked
6	rate limited (retry after backoff)
7	provider unavailable (credits released)
8	generation failed

agent workflow

a typical coding-agent loop: generate with --json --out, parse the result, and branch on the exit code.

shell

#!/usr/bin/env bash
set -euo pipefail

result=$(imaagine generate "$PROMPT" \
  --out ./public/hero.png \
  --model basic --resolution 1K \
  --idempotency-key "$BUILD_ID" \
  --json) || code=$?

if [ "${code:-0}" -eq 4 ]; then
  echo "out of credits — see /pricing" >&2
  exit 4
fi

echo "$result" | jq -r '.image.path'

see the API docs → to call the same endpoints directly from a long-running agent.