{
  "markdown": "# ClipUGC CLI\n\nOfficial command-line interface for **[ClipUGC](https://clipugc.com)** — create AI\ninfluencers, generate photorealistic looks of the same person, turn them into\nsilent-reaction clips, and merge your app's screen recording into a ready-to-post\nUGC ad. All from the terminal; nothing renders locally.\n\n```bash\nnpm install -g clipugc\nclipugc auth login\n```\n\nRequires **Node.js >= 20**. Create an API key in the\n[ClipUGC dashboard](https://clipugc.com/dashboard) (API keys section).\nAPI keys are available on paid plans (Professional and Business).\n\n## Use it with Claude Code\n\nThe fastest way in: this repo ships three Claude Code skills, so you describe what\nyou want instead of learning flags. `clipugc` drives the CLI conversationally,\n`ugc-director` turns an app idea into a complete ad plan, and `persona-account`\nruns an ongoing AI creator account.\n\n```\n/plugin marketplace add clipugc/ClipUGC-CLI\n/plugin install clipugc@ClipUGC-CLI\n```\n\nInstalled as a plugin, the skills are namespaced under it:\n\n```\n/clipugc:ugc-director make a TikTok ad for my habit tracker app\n/clipugc:persona-account create an AI influencer for a fitness account\n/clipugc:clipugc how many credits do I have left\n```\n\n(Cloning the repo instead? Claude Code reads `.claude/skills/` directly and the\nskills are unprefixed — `/ugc-director`, `/persona-account`, `/clipugc`.)\n\nSee **[docs/skills.md](docs/skills.md)** for what each skill knows.\n\nPrefer flags? Everything below works standalone — the skills just drive the same CLI.\n\n## Use from Claude Code / Cursor\n\n[![smithery badge](https://smithery.ai/badge/clipugc/clipugc)](https://smithery.ai/servers/clipugc/clipugc)\nListed on the [MCP Registry](https://registry.modelcontextprotocol.io/?search=clipugc) and [Smithery](https://smithery.ai/servers/clipugc/clipugc).\n\nThe CLI is also an MCP server. `clipugc mcp` speaks the Model Context Protocol over\nstdio, so any MCP client can create characters, looks, clips and merged ads as tools,\nwithout shelling out to the commands above.\n\nLog in once so the server has a key (it reads the same `~/.config/clipugc/config.json`\nthe CLI uses):\n\n```bash\nnpm install -g clipugc\nclipugc auth login\n```\n\n**Claude Code**\n\n```bash\nclaude mcp add clipugc -- npx -y clipugc@latest mcp\n```\n\n`@latest` matters: without it npx reuses any `clipugc` already installed on\nyour machine, and a global install older than 1.2.0 has no `mcp` command, so\nClaude Code reports \"Connection closed\". If you still see that, update the old\ninstall with `npm i -g clipugc@latest`, or run `npx -y clipugc@latest mcp` once in\na terminal so the download finishes (Ctrl+C after \"11 tools ready\"). Do not add\nit from inside a checkout of this repo: there npx resolves `clipugc` to the\nlocal project instead of the npm package.\n\n**Cursor** (Settings > MCP, or `.cursor/mcp.json` in your project)\n\n```json\n{\n  \"mcpServers\": {\n    \"clipugc\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"clipugc@latest\", \"mcp\"]\n    }\n  }\n}\n```\n\nIf you would rather not run `clipugc auth login` on that machine, add an `env` block\nwith `CLIPUGC_API_KEY` set to a key from the dashboard.\n\n**Claude Desktop**\n\nClaude Desktop installs the server as an extension, so there is no config file to edit\nand no Node install needed beyond the app itself:\n\n1. Download [clipugc.mcpb](https://github.com/clipugc/ClipUGC-CLI/releases/latest/download/clipugc.mcpb)\n   from the latest GitHub release.\n2. Double-click the file, or open Claude Desktop, go to **Settings > Extensions**,\n   and choose **Install Extension** (Advanced settings on some versions).\n3. Paste your ClipUGC API key when asked. Create one in the\n   [dashboard](https://clipugc.com/dashboard) under API Keys.\n\nThe extension runs the same `clipugc mcp` server as above. To build the bundle\nyourself, run `npm run build:mcpb` (see \"Local development\").\n\nPrompts: `make_ugc_video`, `new_ai_influencer`, `hook_ideas` (ready-made starts for the\ncommon jobs). Resources: `clipugc://pipeline` (the order of calls) and `clipugc://pricing`\n(documented credit costs; `get_credits` has the live table).\n\nTools: `list_characters`, `create_character`, `generate_image`, `list_images`,\n`create_clip`, `create_motion_clip`, `merge_ad`, `get_video`, `download_video`,\n`get_credits`, `list_hooks`. Arguments follow the CLI flags (`--per-page` becomes\n`per_page`). Generation tools return the job id right away, like the CLI without\n`--wait`; poll with `get_video` (clips and ads) or `list_images` (looks) until the\nstatus is `completed`. Every tool reports its credit cost in its description, and\n`get_credits` returns the live prices.\n\n## What it produces\n\nOne character, cast once. Every picture below is the **same person** — only the\nsetting, outfit and lighting change, because each look is generated from her base\nimage rather than from the description again:\n\n![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)\n\n```bash\nclipugc characters create --wait \\\n  --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.\" \\\n  --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\"\n\n# every look after that: same face, new setting — never re-describe the person\nclipugc images generate --character <id> --wait \\\n  --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\"\n```\n\nThen any look becomes a **silent reaction clip**. Mouth closed throughout — lip-sync\nfrom a still image is the giveaway that a video is AI, so the format is a held\nexpression plus a text hook, not talking:\n\n<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\">\n\n```bash\nclipugc videos create --image <lookId> --duration 5 --wait \\\n  --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.\"\n```\n\nNote the shape of that prompt: an **arc in beats** (glance down → back up → smirk\nforms), an explicit no-talking clause, and ambient motion. Ask for a state instead\nof a progression — \"she smirks\" — and the face morphs. The full library of ~30\nreactions across nine emotion families lives in the\n[`ugc-director`](docs/skills.md) skill.\n\nMerging that clip with your screen recording and a hook is free, so the last step\ncosts nothing and you can test as many hooks as you like.\n\n## How it works\n\n| | Step | Cost |\n|---|---|---|\n| 1 | **Cast an AI character** — described in plain words; the server builds a structured appearance \"DNA\" and the first look | 2 credits |\n| 2 | **Generate looks** — the same face in new settings, outfits and lighting | 2 credits each |\n| 3 | **Animate a look** — a short silent reaction clip (mouth closed; lip-sync is what makes AI video look fake) | 7 (5s) / 13 (10s) |\n| 4 | **Merge into an ad** — your screen recording + a hook text overlay + optional music | **free** |\n\nEvery look after the first is generated **from the character's base image**, so the\nface stays the same person across an entire campaign or grid. That consistency is\nthe point of the product.\n\nFull pricing: image 2 · clip 7 (5s) / 13 (10s) · motion control 3 per second of\ndriver video (capped at 30s) · scene-staged clip 9 (5s) / 15 (10s) · **merge free**.\nCharges are duration-aware and refunds return the exact amount charged. Check live\nvalues with `clipugc credits`.\n\n## Quickstart (plain CLI)\n\n```bash\n# 1. Cast her. Be specific — this is what decides whether she looks like a real\n#    creator or like generic AI. (See the casting guide for the formula.)\nclipugc characters create --wait \\\n  --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.\" \\\n  --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\"\n\n# 2. Animate the look into a 5s silent reaction.\nclipugc videos create --image <lookId> --duration 5 --wait \\\n  --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.\"\n\n# 3. Merge your app recording under a hook. Free, so test as many hooks as you like.\nclipugc videos merge <videoId> --app-video ./screenrec.mp4 --hook \"nobody talks about this app\" --wait\n\n# 4. Download the finished ad — by AD id, not the clip id.\nclipugc ads download <adId> -o ugc-ad.mp4\n```\n\nAdd `--json` to any command for machine-readable output, and `--wait` to any\ngeneration command to poll with a spinner until it completes.\n\n## Example prompts\n\nThe prompt is the product. Below is one of each kind; the full libraries are in\n[docs/casting.md](docs/casting.md) (9 nationalities) and the\n[`ugc-director`](docs/skills.md) skill (~30 reactions across 9 emotion families).\n\n**Casting** — concrete features → an explicit attractiveness claim → directed makeup\nand lighting → a realism anchor. All four parts, or she comes out looking like AI:\n\n<details>\n<summary><b>Blonde Scandinavian</b> — the fastest way to see what this tool does</summary>\n\n```bash\nclipugc characters create --wait \\\n  --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.\" \\\n  --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\"\n```\n</details>\n\n<details>\n<summary><b>Russian</b> — ash-blonde, high broad cheekbones, cool and reserved</summary>\n\n```bash\nclipugc characters create --wait \\\n  --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.\" \\\n  --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\"\n```\n</details>\n\n<details>\n<summary><b>Ukrainian</b> — honey-brown, soft oval face, warm and open</summary>\n\n```bash\nclipugc characters create --wait \\\n  --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.\" \\\n  --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\"\n```\n</details>\n\n**Looks** — never re-describe the person; the base image carries the face. Change only\nthe setting, outfit and light:\n\n```bash\nclipugc images generate --character <id> --wait \\\n  --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\"\n\nclipugc images generate --character <id> --wait \\\n  --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\"\n```\n\n**Reactions** — an arc in beats, a held ending, ambient motion, and an explicit\nno-talking clause every time:\n\n<details>\n<summary><b>Smirk</b> — \"I know something you don't\"</summary>\n\n```\nHandheld 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.\n```\n</details>\n\n<details>\n<summary><b>Jaw-drop</b> — the result reveal</summary>\n\n```\nHandheld 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.\n```\n</details>\n\n<details>\n<summary><b>Dreamy cheek-rest</b> — the soft beat a persona grid runs on</summary>\n\n```\nNearly 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.\n```\n</details>\n\n<details>\n<summary><b>Head-shake</b> — \"why did nobody tell me\"</summary>\n\n```\nHandheld 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.\n```\n</details>\n\n**Hooks** — the text burned over the clip. Re-merging is free, so ship 2-3 variants of\nevery ad and let the platform pick:\n\n```\nnobody talks about this app\nwhy did nobody tell me\nI stopped paying for 4 apps\nPOV: you finally organised your week\n```\n\n## Documentation\n\n| Guide | What's in it |\n|---|---|\n| **[Casting prompts](docs/casting.md)** | The four-part formula behind a good-looking influencer, plus ready-made castings — Scandinavian, Californian, Mediterranean, Korean, Russian, Ukrainian, Polish, Moldovan, Czech |\n| **[Promoting your app](docs/promoting-your-app.md)** | The end-to-end ad walkthrough, hook A/B testing, and who to cast for which app category |\n| **[Command reference](docs/commands.md)** | Every command and flag, with credit costs |\n| **[Configuration](docs/configuration.md)** | Config file, environment variables, exit codes |\n| **[Claude Code skills](docs/skills.md)** | Drive all of this in natural language instead of by flag |\n\n## Local development\n\n```bash\nnpm ci\nnpm run build     # compile TypeScript to dist/\nnpm test          # run the vitest suite\nnpm run dev       # run from source (tsx src/index.ts)\nnpm run build:mcpb  # build the Claude Desktop extension: dist-mcpb/clipugc.mcpb\n                    # also writes dist-mcpb/clipugc-smithery.mcpb for `smithery mcp publish`\n```\n\n`manifest.json` and `icon.png` at the repo root describe the Claude Desktop\nextension. The build script stages `dist/`, `package.json` and a production-only\n`node_modules/` in `dist-mcpb/stage/`, validates the manifest and packs the bundle.\nIts version, name and tool list must match `package.json` and the MCP server; the\ntests check that.\n\n## Privacy Policy\n\nThis CLI and the Claude Desktop extension do not collect anything themselves.\nThere is no analytics, no telemetry and no crash reporting in the code.\n\nWhat leaves your machine: your prompts and tool arguments, the files you choose\nto upload (photos, app screen recordings, driver videos) and your API key. They are\nsent only to `clipugc.com` over HTTPS, and only to run the request you made. The\nAPI key is stored in `~/.config/clipugc/config.json` (CLI) or in Claude Desktop's\nextension settings, and is never sent anywhere else.\n\nHow the ClipUGC service stores and handles that data, including retention and the\nAI providers it uses to render videos, is described in the ClipUGC privacy policy:\n<https://clipugc.com/privacy-policy>.\n\nQuestions or deletion requests: <clipugc@gmail.com>.\n\n## License\n\nMIT\n",
  "bytes": 17809,
  "sha": "d98eaa1e796fb9880d0214460224c90a45a70ff5afc98312c9d52da7a58971e4",
  "repo_slug": "clipugc/clipugc-cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_clipugc_clipugc_ff294c65/readme"
}