gen-ai-use

gen-ai CLI — Usage Guide

The gen-ai CLI generates AI images, videos, and audio from the terminal via the Picsart API.

When to Use

See the description above.

Prerequisites

Picsart gen-ai CLI installed and authenticated (gen-ai login). Note that gen-ai whoami only reads cached credentials from disk and reports "✓ Authenticated" if a token file exists with the right shape — it doesn't check expiry and makes no network call, so it succeeding is not proof that a subsequent network-dependent command will succeed.

How to Run

Use the agent's terminal tool to invoke gen-ai commands as described in the Procedure below.

Quick Reference

• Auth: login, logout, whoami
• Generation: generate, remove-bg, change-bg, enhance, vectorize, redo, extend
• Models / pricing: models, models info, models compare, pricing, credits, validate
• Batch: batch run, batch status, batch resume
• Drive: upload, upload-to-drive, download, list
• Config: config get | set | list | keys | unset
• History: history, history last, history files, history clear
• Utilities: completion, update

Run gen-ai <command> --help for full flag details, or see references/FLAGS.md.

Procedure

See sections below for the detailed walkthrough.

Pitfalls

• Stale model ID — using a name from memory that's been renamed/removed → run gen-ai models first or gen-ai validate -m <id>.
• Passing --image to a non-i2v video model — it's silently ignored, not auto-mapped. Confirm with gen-ai models info <id>.
• Forgetting --no-input in CI — the CLI sits waiting for an interactive prompt and the job times out. Always pair --script (or --no-input) with non-TTY contexts.
• Mixing --multi and --batch — they're mutually exclusive --input-dir modes; pick one.

Verification

Run gen-ai whoami to confirm authentication, then re-run the failed command with --debug. If the command still fails, check the error type before assuming it's a login problem: AuthError ("Not authenticated...") means credentials are genuinely bad and gen-ai login is the fix; NetworkError (message names a transport failure like "fetch failed", or a proxy/connectivity hint) means the CLI's process can't reach the network — re-running login won't help, restoring/escalating network access will.

Where to look

• Flags & full command list → references/FLAGS.md
• Batch generation (manifests, concurrency, stress tests) → references/BATCH.md
• Picsart Drive (upload, download, list) → references/DRIVE.md
• A local file that an MCP tool needs as a URL → picsart-add-media
• Advanced (validate, extend VEO, interactive mode, piping) → references/ADVANCED.md
• Troubleshooting (dry-run, debug, common errors) → references/TROUBLESHOOTING.md
• Example workflows (image → video, cross-model comparison) → references/EXAMPLES.md
• Shell completions (bash, zsh, fish) → references/COMPLETIONS.md

When NOT to use

• SDK-level integration questions → consult the @picsart/ai-sdk reference / specs/ source
• Picsart web miniapp or mobile flows → unrelated
• New backend models that aren't in the catalog yet → backend MR first; CLI picks them up automatically once they ship in @picsart/ai-sdk

Install & auth

# Signed binary (no Node required) — recommended
curl -fsSL https://picsart.com/gen-ai-cli/install.sh | bash
 
# Or via npm (requires Node 22+)
npm install -g @picsart/gen-ai
 
gen-ai

Generate

Image operations

All operation commands accept the same output flags as generate (--download, --save-to-drive, --drive-folder, --open, --clipboard, --json, --quiet, etc.). See references/FLAGS.md.

Browse models, check pricing

Model IDs change as new versions ship — always check the live catalog:

Important defaults

• Drive auto-save — results save to Picsart Drive in folder gen-ai-cli by default. Disable with --no-save-to-drive; use --drive-folder NAME for a custom folder.
• startFrame mapping — for i2v models (VEO, Kling i2v, Wan, Luma, Seedance, Runway), -i / --image is auto-mapped to ctx.startFrame.
• Script mode — --script = --silent --quiet --json, the right combo for piping or CI.
• CI mode — pass --no-input to fail fast instead of hanging on interactive prompts.

When to reach for the reference files

• Many generations at once, or retry/resume → references/BATCH.md
• Files in/out of Drive → references/DRIVE.md
• Validation, VEO extension, scripting → references/ADVANCED.md
• A command is failing → references/TROUBLESHOOTING.md
• Chaining (image → video) or comparing models → references/EXAMPLES.md
• Tab completion → references/COMPLETIONS.md
• All flags / all commands → references/FLAGS.md