gen-ai

Picsart's terminal CLI for generating images, video, and audio with every model Picsart supports — single-shot, interactive, scripted, batch, or piped.

gen-ai generate -m flux-pro -p "studio shot of a ceramic cup" -s

Run gen-ai with no arguments to see the banner above and a numbered menu of every command, grouped by Create / Edit / Utility / Browse / Manage / Account. The terminal version is colorized in Picsart gold.

Install

npm (any platform)

npm install -g @picsart/gen-ai

Requires Node.js 22 or newer.

macOS / Linux (signed binary, no Node required)

curl -fsSL https://picsart.com/gen-ai-cli/install.sh | bash

Windows (PowerShell)

iwr https://picsart.com/gen-ai-cli/install.ps1 | iex

After install, verify:

gen-ai --version

Quick start

gen-ai login                                           # one-time browser auth
gen-ai generate                                        # interactive wizard
gen-ai generate -m flux-pro -p "neon ramen shop" -s    # one-shot, scripted
gen-ai                                                 # launch REPL

-s / --script is shorthand for --silent --quiet --json — clean machine output, no spinners, no prompts.

Discovering commands

Every command and flag is self-documented. Some good entry points:

gen-ai --help                  # global help with the full command tree
gen-ai generate --help         # all generation flags, input types, output options
gen-ai remove-bg --help        # background-removal options
gen-ai enhance --help          # upscale & enhancement options
gen-ai models --help           # filter / browse models by mode, provider, type
gen-ai batch run --help        # manifest format, concurrency, resume options
gen-ai pricing --help          # cost calculation with duration, resolution, audio
gen-ai config set --help       # all settings keys with types and descriptions

Inside the REPL you can:

• Type a number matching a menu shortcut to jump straight into that operation
• Type a command name (with or without flags) — e.g. generate -m flux-pro
• Type <command> --help to render a card-styled help for that command
• Type q or hit Ctrl-C twice to quit

Authentication

gen-ai login      # opens Picsart SSO in your browser
gen-ai whoami     # shows the current user
gen-ai logout     # clears credentials
gen-ai credits    # remaining credits on your account

Credentials are stored at ~/.gen-ai/credentials.json (mode 600). The CLI auto-refreshes the access token on 401 — gen-ai login again if refresh fails.

Commands

Generation

| Command | What it does | |---|---| | gen-ai generate | Generate an image, video, or audio from any model | | gen-ai redo | Re-run the previous generation | | gen-ai extend | Extend a VEO video by 7 seconds (chainable with --times) | | gen-ai remove-bg | Remove the background from an image | | gen-ai change-bg | Replace the background of an image | | gen-ai enhance | Upscale / enhance an image | | gen-ai vectorize | Convert a raster image to SVG |

All operations follow the same pipeline: parse flags → resolve inputs (interactive or scripted) → execute → handle output (display, download, save to Drive, write history).

Models

| Command | What it does | |---|---| | gen-ai models | Browse the full catalog with badges and pricing | | gen-ai models info <id> | Detailed card for one model | | gen-ai models compare <a> <b> | Side-by-side comparison |

Batch

| Command | What it does | |---|---| | gen-ai batch run <manifest> | Run a YAML / JSON manifest of generations in parallel | | gen-ai batch status <run-id> | Check progress of a batch run | | gen-ai batch resume <run-id> | Re-run failed jobs from a previous run |

Drive (Picsart cloud storage)

| Command | What it does | |---|---| | gen-ai upload <files...> | Upload local files / folders to Drive | | gen-ai download <uid> | Download a Drive file | | gen-ai list [--folders] | List Drive folders or files (JSON-ready) |

History

| Command | What it does | |---|---| | gen-ai history | Recent generations | | gen-ai history last | Show the most recent generation in detail | | gen-ai history files | Recently used input files (clipboard / picker memory) | | gen-ai history clear | Clear local history |

Config

| Command | What it does | |---|---| | gen-ai config list | Show all settings | | gen-ai config keys | Show available keys with their types | | gen-ai config get <key> | Read one value | | gen-ai config set <key> <value> | Persist a default | | gen-ai config unset <key> | Revert to default |

Available keys: defaultModel, downloadDir, autoOpen, autoClipboard, autoBell, autoNotify, recentFilesCount, imagePreview, autoUpdate.

Other

| Command | What it does | |---|---| | gen-ai pricing | Credit cost for any operation | | gen-ai validate | Pre-flight check: payload, params, credits | | gen-ai update | Self-update to the latest version | | gen-ai version | Print version | | gen-ai completion <bash\|zsh\|fish> | Print shell completion script |

Run gen-ai <command> --help for full flag details on any command.

Common flags

| Flag | Effect | |---|---| | -m, --model <id> | Pick a model (skips the model picker) | | -p, --prompt <text> | Provide the prompt inline | | -i, --image <path-or-url> | Image input (repeatable) | | --seed <N> | Reproducible output (flux / seedance / seedream / wan / qwen) | | --input-dir <dir> | Run the same operation across every file in a folder | | -s, --script | Equivalent to --silent --quiet --json | | --json | Emit machine-readable JSON to stdout | | --quiet, -q | Suppress info / progress | | --no-color | Strip ANSI colors | | --no-input | Fail instead of prompting (useful in CI) | | --debug | Verbose diagnostic output | | -o, --output <path> | Save result to a specific path | | --download | Download the result locally | | --save-to-drive [folder] | Save result to Picsart Drive |

Model-specific flags

These flags only take effect on models whose paramConfig declares the matching descriptor. Pass them to any other model and the SDK silently ignores them.

| Flag | Where it applies | |---|---| | --seed <N> | flux, seedance, seedream, wan, qwen (image / video) | | --language <code> | ElevenLabs TTS — en, fr, de, … | | --voice <id> | ElevenLabs TTS, audio models with named voices | | --rendering-speed | Ideogram v3 / Character (FLASH/TURBO/DEFAULT/QUALITY); Kling video T2V/I2V and Kling Avatar (std/pro) | | --video-id <id> | Chained ops that reference an existing generation | | --remove-bg-noise | ElevenLabs Speech-to-Speech (eleven-sts-v2, eleven-multilingual-sts-v2) | | --source-image-id <id> | recraft-explore-similar (variations of an existing asset) | | --similarity <1-5> | recraft-explore-similar |

# Reproducible image — same prompt + seed = same result
gen-ai generate -m flux-2-pro -p "a red cat" --seed 12345

# ElevenLabs TTS with explicit language
gen-ai generate -m eleven-v3 -p "Hello world" --language en

# Recraft Explore Similar — generate variations of an existing asset
gen-ai generate -m recraft-explore-similar --source-image-id abc123 --similarity 4

# ElevenLabs STS with background-noise removal
gen-ai generate -m eleven-sts-v2 --audio voice.mp3 --remove-bg-noise

Piping & scripting

The CLI is pipe-aware:

echo "logo for a coffee shop" | gen-ai generate -m flux-pro -s

Combined with --json, it composes well with jq:

gen-ai generate -m flux-pro -p "tabby cat" -s | jq -r '.result.url'

--no-input prevents any interactive prompt — fail fast in CI rather than hanging on a missing flag.

Environment variables

| Variable | Purpose | |---|---| | GEN_AI_API_URL | Override the API endpoint (e.g. staging) | | GEN_AI_UPLOAD_URL | Override the upload endpoint | | PICSART_CLI_VERSION | Build-time version string (set by tsup) | | NO_COLOR | Standard NO_COLOR — disables ANSI when set |

Example: run against staging without changing config:

GEN_AI_API_URL=https://api-stage.picsartstage2.com \
GEN_AI_UPLOAD_URL=https://upload-stage.picsartstage2.com \
gen-ai generate ...

Local data

Everything the CLI persists lives under ~/.gen-ai/:

| File | Purpose | |---|---| | credentials.json | OAuth tokens (mode 600) | | config.json | User preferences set via config set | | history.json | Generation history (capped at 500 entries) | | recent-files.json | Recently used input files | | device-id | Anonymous UUIDv4 for analytics | | update-check.json | Cached version-check timestamp | | debug.log | Crash reports (only written on unexpected errors) |

To fully reset: rm -rf ~/.gen-ai/.

Analytics & privacy

The CLI sends anonymous usage telemetry alongside API requests. It contains:

• version — CLI version
• session_id — UUIDv7, regenerated each time gen-ai starts; one ID covers a full REPL session
• device_id — UUIDv4, generated once and stored at ~/.gen-ai/device-id
• country_code, timezone, locale — derived from your system locale (no IP geolocation done client-side)

We never send file contents, prompts, or generated results to anywhere other than the Picsart API endpoint you'd already be calling. To opt out of analytics, delete ~/.gen-ai/device-id after each run (a fresh ID is generated each time but no historical link is kept).

Shell completion

Bash:

gen-ai completion bash > ~/.local/share/bash-completion/completions/gen-ai

Zsh:

gen-ai completion zsh > "${fpath[1]}/_gen-ai"

Fish:

gen-ai completion fish > ~/.config/fish/completions/gen-ai.fish

REPL mode

Run gen-ai with no arguments to enter the interactive REPL — a numbered menu, fuzzy model picker, image preview support (iTerm2 / Kitty), and clipboard-aware file input. Type ? for help, q to quit.

Troubleshooting

"Token refresh failed" → run gen-ai login again.

"Insufficient credits" → gen-ai credits to check; top up at picsart.com.

Hanging on input → add --no-input to error out instead of prompting.

Crash with no detail → re-run with --debug, then check ~/.gen-ai/debug.log.

Want to see the exact request being sent → set GEN_AI_API_URL=http://localhost:PORT and point at a local proxy.

Architecture

The CLI uses a 5-layer pipeline (entry → commands → resolvers → execution → output) with strict import boundaries enforced by dependency-cruiser. See ARCHITECTURE.md for the full layout.

Models live in the @picsart/ai-sdk workspace package (specs/src/vendors/catalog/), not in the CLI itself — adding a new model makes it appear in gen-ai automatically.

Links

• Picsart: https://picsart.com
• API docs: https://docs.picsart.io
• Issues: https://gitlab.com/picsart/web/miniapp-projects/ai-toolkit/-/issues

License

MIT © Picsart