ClipUGC CLI

Official command-line interface for ClipUGC — create AI influencers, generate photorealistic looks of the same person, turn them into silent-reaction clips, and merge your app's screen recording into a ready-to-post UGC ad. All from the terminal; nothing renders locally.

npm install -g clipugc
clipugc auth login

Requires Node.js >= 20. Create an API key in the ClipUGC dashboard (API keys section). API keys are available on paid plans (Professional and Business).

Use it with Claude Code

The fastest way in: this repo ships three Claude Code skills, so you describe what you want instead of learning flags. clipugc drives the CLI conversationally, ugc-director turns an app idea into a complete ad plan, and persona-account runs an ongoing AI creator account.

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

Installed as a plugin, the skills are namespaced under it:

/clipugc:ugc-director make a TikTok ad for my habit tracker app
/clipugc:persona-account create an AI influencer for a fitness account
/clipugc:clipugc how many credits do I have left

(Cloning the repo instead? Claude Code reads .claude/skills/ directly and the skills are unprefixed — /ugc-director, /persona-account, /clipugc.)

See docs/skills.md for what each skill knows.

Prefer flags? Everything below works standalone — the skills just drive the same CLI.

Use from Claude Code / Cursor

Listed on the MCP Registry and Smithery.

The CLI is also an MCP server. clipugc mcp speaks the Model Context Protocol over stdio, so any MCP client can create characters, looks, clips and merged ads as tools, without shelling out to the commands above.

Log in once so the server has a key (it reads the same ~/.config/clipugc/config.json the CLI uses):

npm install -g clipugc
clipugc auth login

Claude Code

claude mcp add clipugc -- npx -y clipugc@latest mcp

@latest matters: without it npx reuses any clipugc already installed on your machine, and a global install older than 1.2.0 has no mcp command, so Claude Code reports "Connection closed". If you still see that, update the old install with npm i -g clipugc@latest, or run npx -y clipugc@latest mcp once in a terminal so the download finishes (Ctrl+C after "11 tools ready"). Do not add it from inside a checkout of this repo: there npx resolves clipugc to the local project instead of the npm package.

Cursor (Settings > MCP, or .cursor/mcp.json in your project)

{
  "mcpServers": {
    "clipugc": {
      "command": "npx",
      "args": ["-y", "clipugc@latest", "mcp"]
    }
  }
}

If you would rather not run clipugc auth login on that machine, add an env block with CLIPUGC_API_KEY set to a key from the dashboard.

Claude Desktop

Claude Desktop installs the server as an extension, so there is no config file to edit and no Node install needed beyond the app itself:

1. Download clipugc.mcpb from the latest GitHub release.
2. Double-click the file, or open Claude Desktop, go to Settings > Extensions, and choose Install Extension (Advanced settings on some versions).
3. Paste your ClipUGC API key when asked. Create one in the dashboard under API Keys.

The extension runs the same clipugc mcp server as above. To build the bundle yourself, run npm run build:mcpb (see "Local development").

Prompts: make_ugc_video, new_ai_influencer, hook_ideas (ready-made starts for the common jobs). Resources: clipugc://pipeline (the order of calls) and clipugc://pricing (documented credit costs; get_credits has the live table).

Tools: list_characters, create_character, generate_image, list_images, create_clip, create_motion_clip, merge_ad, get_video, download_video, get_credits, list_hooks. Arguments follow the CLI flags (--per-page becomes per_page). Generation tools return the job id right away, like the CLI without --wait; poll with get_video (clips and ads) or list_images (looks) until the status is completed. Every tool reports its credit cost in its description, and get_credits returns the live prices.

What it produces

One character, cast once. Every picture below is the same person — only the setting, outfit and lighting change, because each look is generated from her base image rather than from the description again:

clipugc characters create --wait \
  --description "Very pretty Danish woman aged 22, light blonde fine hair to her shoulders with a middle parting, pale blue upturned eyes, heart-shaped face, porcelain cool-toned skin. Genuinely attractive Instagram-creator look, but reads as a real girl — natural skin texture with visible pores, not airbrushed." \
  --scene "close selfie in a softly lit bedroom at golden hour, warm low sun through the window behind her giving a rim light on her hair, full glam makeup with smoky bronze eyeshadow and glossy nude lips, phone-camera quality with mild grain, slightly off-centre framing"

# every look after that: same face, new setting — never re-describe the person
clipugc images generate --character <id> --wait \
  --scene "bathroom mirror selfie in the evening, phone visible in her hand, warm vanity lights either side of the mirror, polished makeup with glowing skin and glossy lips, phone-camera quality with grain, slightly off-centre framing"

Then any look becomes a silent reaction clip. Mouth closed throughout — lip-sync from a still image is the giveaway that a video is AI, so the format is a held expression plus a text hook, not talking:

clipugc videos create --image <lookId> --duration 5 --wait \
  --prompt "She glances down at the phone, back up to the lens, and one corner of her mouth pulls into a smirk she is clearly trying to suppress. Her lips stay closed and together for the entire clip. She does not speak, does not mouth any words, and her mouth never opens. Natural handheld movement, she shifts slightly, hair moves. Ordinary phone-camera footage, visible grain."

Note the shape of that prompt: an arc in beats (glance down → back up → smirk forms), an explicit no-talking clause, and ambient motion. Ask for a state instead of a progression — "she smirks" — and the face morphs. The full library of ~30 reactions across nine emotion families lives in the ugc-director skill.

Merging that clip with your screen recording and a hook is free, so the last step costs nothing and you can test as many hooks as you like.

How it works

Every look after the first is generated from the character's base image, so the face stays the same person across an entire campaign or grid. That consistency is the point of the product.

Full pricing: image 2 · clip 7 (5s) / 13 (10s) · motion control 3 per second of driver video (capped at 30s) · scene-staged clip 9 (5s) / 15 (10s) · merge free. Charges are duration-aware and refunds return the exact amount charged. Check live values with clipugc credits.

Quickstart (plain CLI)

# 1. Cast her. Be specific — this is what decides whether she looks like a real
#    creator or like generic AI. (See the casting guide for the formula.)
clipugc characters create --wait \
  --description "Very pretty Danish woman aged 22, light blonde fine hair to her shoulders with a middle parting, pale blue upturned eyes, heart-shaped face, porcelain cool-toned skin. Genuinely attractive Instagram-creator look, but reads as a real girl — natural skin texture with visible pores, not airbrushed." \
  --scene "close selfie in a softly lit bedroom at golden hour, warm rim light on her hair, full glam makeup with winged liner and glossy lips, natural skin texture, amateur front-camera phone quality, headroom above her head for text"

# 2. Animate the look into a 5s silent reaction.
clipugc videos create --image <lookId> --duration 5 --wait \
  --prompt "Handheld selfie framing, slight drift. Her expression gradually shifts from neutral to amazed — eyebrows rise, eyes widen, lips part slightly in a silent gasp — then she breaks into a delighted grin and holds it, looking straight into the camera. Hair moves subtly. No talking."

# 3. Merge your app recording under a hook. Free, so test as many hooks as you like.
clipugc videos merge <videoId> --app-video ./screenrec.mp4 --hook "nobody talks about this app" --wait

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

Add --json to any command for machine-readable output, and --wait to any generation command to poll with a spinner until it completes.

Example prompts

The prompt is the product. Below is one of each kind; the full libraries are in docs/casting.md (9 nationalities) and the ugc-director skill (~30 reactions across 9 emotion families).

Casting — concrete features → an explicit attractiveness claim → directed makeup and lighting → a realism anchor. All four parts, or she comes out looking like AI:

clipugc characters create --wait \
  --description "Very pretty Danish woman aged 22, light blonde fine hair to her shoulders with a middle parting and natural movement, pale blue upturned eyes, heart-shaped face, porcelain cool-toned skin, soft pink lips, gentle jawline. Calm, faintly teasing expression. Genuinely attractive Instagram-creator look, but reads as a real girl — natural skin texture with visible pores, not airbrushed." \
  --scene "close selfie in a softly lit bedroom at golden hour, warm low sun through the window behind her giving a rim light on her hair, full glam makeup with winged liner, long lashes and glossy lips, natural skin texture, amateur front-camera phone quality, headroom above her head for text"

clipugc characters create --wait \
  --description "Very pretty Russian woman aged 22 from Moscow, ash-blonde straight hair below her shoulders with a middle parting, cool grey-blue almond eyes set wide apart, high broad cheekbones, straight narrow nose, fair cool-toned skin, medium lips with a defined cupid's bow, fine straight brows. Reserved, slightly aloof expression that warms when she smiles. Strikingly attractive Instagram-creator look, yet unmistakably a real person — natural skin texture with visible pores, not airbrushed." \
  --scene "close selfie in a softly lit bedroom at golden hour, warm low sun behind her giving a rim light on her hair, soft glam makeup with winged liner and a nude glossy lip, natural skin texture, amateur front-camera phone quality, headroom above her head for text"

clipugc characters create --wait \
  --description "Very pretty Ukrainian woman aged 21 from Kyiv, honey-brown hair with a soft natural wave past her shoulders, warm green eyes with a gentle upturn, soft oval face with a rounded chin, light golden-toned skin, full lips, softly arched brows, a small mole above her lip. Warm, open, easy-smiling energy. Genuinely attractive Instagram-creator look that reads as a real girl — natural skin texture with visible pores, not airbrushed." \
  --scene "front-camera phone selfie by a large window in a bright apartment, soft diffused daylight on her face, plants blurred behind, everyday makeup with fluffy brows and a glossy lip, natural skin texture, amateur phone quality, headroom above the head for text"

Looks — never re-describe the person; the base image carries the face. Change only the setting, outfit and light:

clipugc images generate --character <id> --wait \
  --scene "mirror selfie in a bathroom in the evening, phone visible in her hand, warm vanity lights either side of the mirror, polished makeup with glowing skin and blush, natural skin texture, amateur phone quality, headroom above the head for text"

clipugc images generate --character <id> --wait \
  --scene "sitting in the driver's seat of a parked car in daylight, seatbelt on, daylight through the windscreen, natural skin texture, amateur phone quality, headroom above the head for text"

Reactions — an arc in beats, a held ending, ambient motion, and an explicit no-talking clause every time:

Handheld selfie framing with tiny natural wobble. She looks directly into the camera, one eyebrow raises slightly, a knowing smirk slowly spreads across her face, and she nods slowly twice, lips closed, holding eye contact the entire time. Hair moves subtly. No talking, mouth stays closed.

Handheld selfie framing, slight drift. Her expression gradually shifts from neutral to amazed — eyebrows rise, eyes widen, lips part slightly in a silent gasp — then she breaks into a delighted grin and holds it, looking straight into the camera. Hair moves subtly. No talking.

Nearly static selfie framing with subtle handheld drift. She rests her cheek against her palm, elbow anchored, eyes softening as a slow warm closed-mouth smile spreads, gaze drifting slightly off camera then returning to the lens, holding it. Hair moves subtly. No talking.

Handheld selfie framing, slight wobble. She exhales through her nose, shakes her head slowly with a rueful closed-mouth smile, briefly glances up at the ceiling, then back into the camera with an amused resigned look, holding it. Hair follows the motion naturally. No talking.

Hooks — the text burned over the clip. Re-merging is free, so ship 2-3 variants of every ad and let the platform pick:

nobody talks about this app
why did nobody tell me
I stopped paying for 4 apps
POV: you finally organised your week

Documentation

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)
npm run build:mcpb  # build the Claude Desktop extension: dist-mcpb/clipugc.mcpb
                    # also writes dist-mcpb/clipugc-smithery.mcpb for `smithery mcp publish`

manifest.json and icon.png at the repo root describe the Claude Desktop extension. The build script stages dist/, package.json and a production-only node_modules/ in dist-mcpb/stage/, validates the manifest and packs the bundle. Its version, name and tool list must match package.json and the MCP server; the tests check that.

Privacy Policy

This CLI and the Claude Desktop extension do not collect anything themselves. There is no analytics, no telemetry and no crash reporting in the code.

What leaves your machine: your prompts and tool arguments, the files you choose to upload (photos, app screen recordings, driver videos) and your API key. They are sent only to clipugc.com over HTTPS, and only to run the request you made. The API key is stored in ~/.config/clipugc/config.json (CLI) or in Claude Desktop's extension settings, and is never sent anywhere else.

How the ClipUGC service stores and handles that data, including retention and the AI providers it uses to render videos, is described in the ClipUGC privacy policy: https://clipugc.com/privacy-policy.

Questions or deletion requests: clipugc@gmail.com.

License

MIT