CLI

The Depicta CLI lets you generate, edit, and process images from your terminal. Both the Python and Node.js CLIs have identical commands.

Install

Python

pip install depicta

Or run without installing: uvx depicta@latest (@latest avoids a stale cached version)

Node.js

npm install -g depicta

Or run without installing: npx depicta@latest (@latest avoids a stale cached version)

Authenticate

depicta uvx depicta npx depicta

depicta auth login

This prompts for your API key interactively. Alternatively, set the DEPICTA_API_KEY environment variable:

export DEPICTA_API_KEY=dpct_your_key_here

Your key is stored in ~/.config/depicta/config.json with 0600 permissions.

Generate your first image

depicta image "A sunset over Greek mountains, warm golden light"

The CLI downloads the image and shows the file path, cost, and remaining balance:

✓ Saved to image-20260406-143022.png
  Cost: EUR 0.036000
  Balance: EUR 9.964000

Cost and balance are in credits (EUR, excluding VAT; VAT is added when you buy credits).

More examples

# Generate a graphic (icon, logo, clipart)
depicta graphic "A minimal rocket icon, white on a solid navy background, 256x256"

# Generate a diagram
depicta diagram "User authentication flow" --type flowchart

# Edit an existing image
depicta edit image photo.png "Make the sky more dramatic"

# Combine two images
depicta combine image hero.png overlay.png --prompt "Side by side comparison"

Output modes

The CLI auto-detects how you’re using it:

Mode	When	Output
Human	Terminal (TTY), or --human	Formatted status + file path
JSON	--json flag	Full JSON to stdout
Pipe	Piped to another command	File path only to stdout

Errors follow the same mode: with --json you get the error as JSON (the API’s error, message and details, unchanged), and with --human a readable Error: <message> followed by one line per failing field, so you can see what to fix. Both are printed to stderr.

Piping

Chain commands together — output flows directly to the next operation:

depicta image "A product photo" | depicta process remove-bg - | depicta process resize - --width 512

Exit codes

Code	Meaning
0	Success
1	General error, including every 403 (for example a model outside your allowed models, or a suspended account)
2	Missing or invalid API key (401)
3	Insufficient credits (402)
4	Content rejected (451)
5	Rate limited (429)

The CLI first retries a 429 itself: up to 3 attempts, waiting as long as the Retry-After header says, for up to about 30 seconds in all. Exit 5 means those retries ran out; the JSON error then carries retry_after, the seconds to wait.

See Error codes for the full mapping.

Next steps

• Generate — content types, models, reference images
• Processing — 21 operations
• Models — available models and pricing