clipugc

ClipUGC CLI

Official command-line interface for ClipUGC — create AI characters, generate photorealistic looks, and produce UGC-style marketing videos for your mobile app straight from the terminal.

ClipUGC makes AI-generated, influencer-style UGC (user-generated-content) ads for mobile apps. The workflow:

• Create an AI character — a structured appearance "DNA" (age, gender, nationality, vibe, hair, eyes, skin tone, body type…).
• Generate looks — photorealistic reference images of the character (different shots, templates, and scenes).
• Create video clips — turn a selected look (or your own photo) into short talking/moving clips.
• Merge into a UGC ad — combine a clip with your app's screen recording and a hook text (plus optional music) into a final, ready-to-post UGC ad.

Credits are consumed server-side per action: image = 2, clip (5s) = 7, clip (10s) = 13, motion control = 3 per second of driver video (rounded up, capped at 30s), scene-staged clip (--scene) = image + clip (9 for 5s, 15 for 10s), merge = 1. Charges are duration-aware, and refunds return the exact amount charged. Check your balance and the live cost of each action anytime with clipugc credits, and your ledger with clipugc credits history.

Installation

Requires Node.js >= 20.

npm install -g clipugc

Then authenticate with an API key. Create one in the ClipUGC dashboard (API keys section):

clipugc auth login

Quickstart

End-to-end: character → looks → clip → final UGC ad.

# 1. Authenticate (prompts for your API key)
clipugc auth login

# 2. Check your credit balance and per-action costs
clipugc credits

# 3. Create an AI character
clipugc characters create --description "casual gen-z woman in her early 20s, brown hair, friendly smile"

# 4. Generate reference looks for the character (waits until done)
clipugc images generate --character <characterId> --shots frontal,three_quarter --wait

# 5. Pick the look you like best
clipugc images list --character <characterId>

# 6. Turn the selected look into a short video clip
clipugc videos create --image <imageId> --prompt "excitedly talking to camera about a new app" --wait

# 7. Merge the clip with your app's screen recording + a hook.
#    This creates an AD, which has its own id (printed, or `merged_video_id` with --json).
clipugc videos merge <videoId> --app-video ./screenrec.mp4 --hook "This app fixed my morning routine" --wait

# 8. Download the final UGC ad — by AD id, not the clip id
clipugc ads download <adId> -o ugc-ad.mp4

Tip: add --json to any command to get raw JSON (handy for grabbing ids in scripts), and --wait to any generation command to poll with a spinner until it completes.

Commands

Auth

Command	Description
clipugc auth login [--api-key <key>]	Authenticate the CLI. Prompts securely for the key if --api-key is omitted, validates it against the API, and stores it.
clipugc auth status	Show whether you are logged in and as whom.
clipugc auth logout	Remove the stored API key.
clipugc whoami	Show the authenticated account.

Config

Command	Description
clipugc config list	Show all config values.
clipugc config get <key>	Read one config value.
clipugc config set <key> <value>	Set a config value (apiBaseUrl, apiKey, email).
clipugc config path	Print the config file path.

Credits and account

Command	Description
clipugc credits	Show credit balance and per-action costs.
clipugc credits history [--per-page <n>] [--page <n>]	Show your credit transaction history (spends, top-ups, refunds) as a paginated table. Add --json for scripting.
clipugc credits packs	List purchasable credit packs (buy on the web dashboard / mobile app).
clipugc account delete [--yes]	Permanently delete your account. Double confirmation (y/N, then type DELETE); --yes skips both.

Characters

Command	Description
clipugc characters list [--discover|--mine|--feed] [--search <q>] [--page N] [--per-page N]	List characters. --discover shows public characters, --mine only yours, --feed combines both (your characters newest-first, then public ones in unlock order — a Locked column marks locked rows). --per-page max 50.
clipugc characters create --description "…" [--scene "…"] [--inspiration f1.jpg…] [--private] [--make-video [--motion-prompt "…"]] [--wait]	Create a character from a plain-text description — the first look generates automatically (2 credits). Public by default. --make-video also stages the character's first video clip (its id + status are printed for videos follow-ups); --motion-prompt steers that clip's motion.
clipugc characters show <id>	Show a character's details and DNA, plus its display name, video/picture counts, and preview clip when available.
clipugc characters rename <id> --name "New"	Rename a character.
clipugc characters publish <id> / unpublish <id>	Make a character public / private.
clipugc characters delete <id> [--yes]	Delete a character (--yes skips the confirmation).

characters create advanced flags (structured DNA path, rarely needed — use --description instead):

Flag	Values
--name "Full Name"	Required. 2–120 chars.
--age	18–99
--gender	e.g. male | female | other
--dna-json <file-or-inline-json>	Appearance DNA fields (nationality, vibe, hair/eye color, …) as a JSON file path or inline JSON object.

Images (looks)

Command	Description
clipugc images generate --character <id> [flags] [--wait]	Generate reference images (looks) for a character. Costs 2 credits per image.
clipugc images list --character <id>	List a character's images.
clipugc images show <id>	Show image details.
clipugc images download <id> [-o out.png]	Download the look image to disk (-o creates missing parent directories).
clipugc images status <id>	Check generation status.
clipugc images variation <id> --scene "..." [--count 1-4] [--before-after] [--wait]	Generate scene variations of an existing image.
clipugc images retry <id> [--wait]	Retry a failed generation.
clipugc images delete <id> [--yes]	Delete an image.

images generate flags:

Flag	Values
--shots	Comma-separated: frontal, three_quarter, profile, back
--template	model_digitals | scene_recreation | specific_angle
--scene "..."	Scene description, max 600 chars.
--resolution	0.5K | 1K | 2K | 4K
--wait	Poll with a spinner until completed or failed.

Videos

Command	Description
clipugc videos list [--character <id>] [--mergeable | --finals] [--page N] [--per-page N]	List your clips. --character filters to one AI character, --mergeable shows only completed clips not yet merged (ready for videos merge). --finals lists finished ads instead of clips — identical to clipugc ads list, and the ids it prints are ad ids.
clipugc videos create (--image <lookId> | --photo <file>) [flags] [--wait]	Create a video clip from a look or your own photo. Costs 7 credits (5s) or 13 (10s); a --scene staged clip costs 9.
clipugc videos motion (--image <lookId> | --photo <file>) --driver <video.mp4> [--keep-sound] [--wait]	Animate a look/photo using a driver video (mp4/mov, max 50MB, max 30s). Costs 3 credits per second of driver video (rounded up, capped at 30s).
clipugc videos merge <videoId> --app-video <screenrec.mp4> --hook "..." [--music <file.mp3>] [--wait]	Merge a clip with your app's screen recording + a hook (max 150 chars) into a final UGC ad. Costs 1 credit. Prints the new ad id (merged_video_id under --json); --wait blocks until the merge render finishes (or fails, refunding the credit).
clipugc videos show <id>	Show clip details (including the id of the ad made from it, if any).
clipugc videos status <id>	Check generation status.
clipugc videos download <id> [-o out.mp4]	Download the finished clip (-o creates missing parent directories).
clipugc videos retry <id> [--wait]	Retry a failed generation.
clipugc videos delete <id> [--yes]	Delete a clip.

Ads

A finished UGC ad is its own resource, not a flavour of a clip — so it has its own id space. An ad id is not a clip id: clipugc ads download 121 and clipugc videos download 121 address different things. videos merge <clipId> tells you the ad id it created, and deleting an ad leaves the clip it was made from on the influencer's profile.

Command	Description
clipugc ads list [--status <s>] [--page N] [--per-page N]	List your finished ads. --status is one of pending, processing, completed, failed. Same as videos list --finals.
clipugc ads show <adId>	Show ad details: merge status, hook text, watermark, credits charged, source clip id.
clipugc ads download <adId> [-o out.mp4]	Download the finished ad (-o creates missing parent directories; default clipugc-ad-<adId>.mp4).
clipugc ads retry <adId> [--wait]	Re-render a failed ad. Charges the merge credit again, and only works while the app recording is still stored (can_retry).
clipugc ads delete <adId> [--yes]	Delete the ad. The source clip is untouched.

videos create flags:

Flag	Values
--image <lookId> or --photo <file>	One of the two is required. Photo: png/jpg/jpeg/webp.
--prompt "..."	Video prompt, max 1500 chars.
--scene "..."	Scene description, max 600 chars. Makes it a scene-staged clip (image + clip: 9 credits at 5s, 15 at 10s).
--duration	5 | 10 (seconds). 5s = 7 credits, 10s = 13.
--keep-sound	Keep the generated audio.
--wait	Poll until completed or failed.

File uploads are handled automatically via presigned URLs. Accepted formats by purpose: photo png/jpg/jpeg/webp; app video and driver video mp4/mov; music mp3/wav/m4a.

Hooks

Command	Description
clipugc hooks suggest [--context "my app is a habit tracker"]	Get AI-suggested hook texts for your UGC ad.

Configuration

Config file

Settings are stored at ~/.config/clipugc/config.json:

Key	Description
apiBaseUrl	ClipUGC API base URL.
apiKey	Your API key (set by clipugc auth login).
email	Account email (set on login).

Manage with clipugc config list / get / set / path.

Environment variables

Env vars override the config file:

Variable	Overrides
CLIPUGC_API_KEY	apiKey
CLIPUGC_API_BASE_URL	apiBaseUrl

JSON output

Every command accepts the global --json flag to print raw JSON instead of formatted output — use it for scripting and to capture ids:

clipugc characters list --mine --json

Waiting on long-running jobs

Generation commands (images generate, images variation, images retry, videos create, videos motion, videos merge, videos retry, ads retry) accept --wait to poll with a spinner until the job is completed or failed. Without --wait, the command returns immediately and you can poll with images status <id> / videos status <id> / ads show <adId>.

Exit codes

Code	Meaning
0	Success
1	Generic error
2	Validation error
3	Authentication error
4	Not found
5	Premium required
6	Insufficient credits
7	Network error / server unreachable

Claude Code Skills

If you use Claude Code, this repo ships three skills:

• clipugc — drive the whole CLI through natural language, with automatic prerequisite checks (CLI installed, logged in, enough credits) and guided end-to-end workflows.
• ugc-director — a TikTok UGC ad director: turns an app idea into a complete creative plan (silent-reaction archetype, hook text, casting, copy-paste look & video prompts) and executes it with the CLI. Built on research into what actually converts: mouth-closed reaction formats (no lip-sync = no AI uncanny valley), text-overlay hooks, a 12-archetype reaction taxonomy, hook formula library, and a casting matrix by app category.
• persona-account — run an ongoing AI creator account: define a persona once (niche, look, aesthetic, settings, voice, content pillars), then ask for "the next post" and get one on-brand post at a time — same face, rotating settings and reactions, grid composition rules, and a picture-before-video credit gate so you approve the character before any clip credits are spent.

Install via the Claude Code plugin system:

/plugin marketplace add mirzemehdi/ClipUGC-CLI
/plugin install clipugc@ClipUGC-CLI

Or clone this repo and Claude Code picks up the skills from .claude/skills/ when working inside it.

Use:

/ugc-director make a TikTok ad for my habit tracker app
/persona-account create an AI influencer for a fitness account
/persona-account give me the next post
/clipugc create a character for my fitness app ads
/clipugc make a UGC ad from my screen recording
/clipugc how many credits do I have left

Local development

npm ci
npm run build     # compile TypeScript to dist/
npm test          # run the vitest suite
npm run dev       # run from source (tsx src/index.ts)

License

MIT