ClipUGC-CLI

# ClipUGC CLI

Official command-line interface for **[ClipUGC](https://clipugc.com/?utm_source=github-readme&utm_medium=integration&utm_campaign=agent-directories)**, create AI
influencers, generate photorealistic looks of the same person, turn them into
silent-reaction clips, and put your app's screen recording into a ready-to-post
UGC video. All from the terminal; nothing renders locally.

```bash
npm install -g clipugc
clipugc auth login
```

Requires **Node.js >= 20**. Create an API key in the
[ClipUGC dashboard](https://clipugc.com/dashboard?utm_source=github-readme&utm_medium=integration&utm_campaign=agent-directories) (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 UGC video 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 video 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](docs/skills.md)** for what each skill knows.

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

## Install in Gemini CLI, Cursor or VS Code

These use the hosted ClipUGC server at `https://clipugc.com/mcp`. Nothing runs on
your machine and there is no API key to copy: the first call opens a browser so
you can sign in with your ClipUGC account.

**Gemini CLI**

```bash
gemini extensions install https://github.com/clipugc/ClipUGC-CLI
```

This adds the hosted server, a short guide (`GEMINI.md`) and the skills.

**Cursor**

Once the ClipUGC plugin is listed in the Cursor Marketplace, install it there to
get the server and the skills. Until then, add the server by hand in
Settings > MCP or `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "clipugc": {
      "url": "https://clipugc.com/mcp"
    }
  }
}
```

**VS Code** (GitHub Copilot agent mode)

```bash
code --add-mcp '{"name":"clipugc","type":"http","url":"https://clipugc.com/mcp"}'
```

Or search `@mcp clipugc` in the Extensions view once it shows up in the gallery.

## Use from Claude Code / Cursor

[![smithery badge](https://smithery.ai/badge/clipugc/clipugc)](https://smithery.ai/servers/clipugc/clipugc)
Listed on the [MCP Registry](https://registry.modelcontextprotocol.io/?search=clipugc) and [Smithery](https://smithery.ai/servers/clipugc/clipugc).

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 finished videos 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):

```bash
npm install -g clipugc
clipugc auth login
```

**Claude Code**

```bash
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)

```json
{
  "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](https://github.com/clipugc/ClipUGC-CLI/releases/latest/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](https://clipugc.com/dashboard?utm_source=github-readme&utm_medium=integration&utm_campaign=agent-directories) 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 finished videos) 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:

![Six looks of the same AI influencer, golden-hour bedroom, bathroom mirror, parked car, night bathroom, balcony at night, in bed](docs/images/looks.jpg)

```bash
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:

<img src="docs/images/reaction.gif" alt="A silent reaction clip, she glances down at her phone, back up to the lens, and a suppressed smirk forms, mouth closed throughout" width="230">

```bash
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`](docs/skills.md) skill.

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

## How it works

| | Step | Cost |
|---|---|---|
| 1 | **Cast an AI character**: described in plain words; the server builds a structured appearance "DNA" and the first look | 2 credits |
| 2 | **Generate looks**: the same face in new settings, outfits and lighting | 2 credits each |
| 3 | **Animate a look**: a short silent reaction clip (mouth closed; lip-sync is what makes AI video look fake) | 7 (5s) / 13 (10s) |
| 4 | **Finish the video**: your screen recording + a hook text overlay + optional music | **free** |

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) · **finished video free**.
Charges are duration-aware and refunds return the exact amount charged. Check live
values with `clipugc credits`.

## Quickstart (plain CLI)

```bash
# 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 gir