clipugc 0.2.0

package/README.md

@@ -0,0 +1,249 @@
+# ClipUGC CLI
+
+Official command-line interface for [ClipUGC](https://clipugc.com) — 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:
+
+1. **Create an AI character** — a structured appearance "DNA" (age, gender, nationality, vibe, hair, eyes, skin tone, body type…).
+2. **Generate looks** — photorealistic reference images of the character (different shots, templates, and scenes).
+3. **Create video clips** — turn a selected look (or your own photo) into short talking/moving clips.
+4. **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**.
+
+```bash
+npm install -g clipugc
+```
+
+Then authenticate with an API key. Create one in the [ClipUGC dashboard](https://clipugc.com/dashboard) (API keys section):
+
+```bash
+clipugc auth login
+```
+
+## Quickstart
+
+End-to-end: character → looks → clip → final UGC ad.
+
+```bash
+# 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
+clipugc videos merge <videoId> --app-video ./screenrec.mp4 --hook "This app fixed my morning routine" --wait
+
+# 8. Download the final UGC ad
+clipugc videos download <videoId> -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 videos. `--character` filters to one AI character, `--mergeable` shows only completed clips not yet merged (ready for `videos merge`), `--finals` shows only merged final UGC videos. |
+| `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 the final UGC ad. Costs 1 credit. `--wait` blocks until the merge render finishes (or fails, refunding the credit). |
+| `clipugc videos show <id>` | Show video details. |
+| `clipugc videos status <id>` | Check generation status. |
+| `clipugc videos download <id> [-o out.mp4]` | Download the finished video (`-o` creates missing parent directories). |
+| `clipugc videos retry <id> [--wait]` | Retry a failed generation. |
+| `clipugc videos delete <id> [--yes]` | Delete a video. |
+
+`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:
+
+```bash
+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`) 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>`.
+
+### 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](https://claude.ai/code), this repo ships two 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.
+
+**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
+/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
+
+```bash
+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

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createCli(): Command;

package/dist/cli.js

@@ -0,0 +1,31 @@
+import { Command } from 'commander';
+import { getVersion } from './version.js';
+import { registerAuthCommands } from './commands/auth.js';
+import { registerConfigCommands } from './commands/config.js';
+import { registerCreditsCommands } from './commands/credits.js';
+import { registerAccountCommands } from './commands/account.js';
+import { registerCharactersCommands } from './commands/characters.js';
+import { registerImagesCommands } from './commands/images.js';
+import { registerVideosCommands } from './commands/videos.js';
+import { registerHooksCommands } from './commands/hooks.js';
+export function createCli() {
+    const program = new Command();
+    program
+        .name('clipugc')
+        .description('ClipUGC CLI — create AI characters, generate looks, and produce UGC-style videos for your mobile app.\n' +
+        'Get an API key from your dashboard at https://clipugc.com, then run `clipugc auth login`.')
+        .version(getVersion(), '-v, --version', 'Print the CLI version')
+        .option('--json', 'Output raw JSON (for scripting)')
+        .showHelpAfterError('(add --help for usage)')
+        .showSuggestionAfterError(true);
+    registerAuthCommands(program);
+    registerConfigCommands(program);
+    registerCreditsCommands(program);
+    registerAccountCommands(program);
+    registerCharactersCommands(program);
+    registerImagesCommands(program);
+    registerVideosCommands(program);
+    registerHooksCommands(program);
+    return program;
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,MAAM,UAAU,SAAS;IACvB,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,SAAS,CAAC;SACf,WAAW,CACV,yGAAyG;QACzG,2FAA2F,CAC5F;SACA,OAAO,CAAC,UAAU,EAAE,EAAE,eAAe,EAAE,uBAAuB,CAAC;SAC/D,MAAM,CAAC,QAAQ,EAAE,iCAAiC,CAAC;SACnD,kBAAkB,CAAC,wBAAwB,CAAC;SAC5C,wBAAwB,CAAC,IAAI,CAAC,CAAC;IAElC,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAChC,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACjC,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACjC,0BAA0B,CAAC,OAAO,CAAC,CAAC;IACpC,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAChC,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAChC,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAE/B,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/commands/account.d.ts

@@ -0,0 +1,12 @@
+import type { Command } from 'commander';
+export interface ConfirmDeps {
+    confirm: (message: string) => Promise<boolean>;
+    promptInput: (message: string) => Promise<string>;
+}
+/**
+ * Double confirmation for account deletion: a yes/No confirm followed by
+ * typing the exact word DELETE. Throws AbortedError when either step fails.
+ * Skipped entirely when `yes` is true (for scripting via --yes).
+ */
+export declare function confirmAccountDeletion(yes: boolean, deps?: ConfirmDeps): Promise<void>;
+export declare function registerAccountCommands(program: Command): void;

package/dist/commands/account.js

@@ -0,0 +1,48 @@
+import { createApiClient } from '../services/api.js';
+import { deleteAccount } from '../services/user.service.js';
+import { loadConfig, saveConfig } from '../utils/config.js';
+import { AbortedError } from '../utils/errors.js';
+import { logger } from '../utils/logger.js';
+import { isJsonMode, printJson } from '../utils/output.js';
+import { confirm as confirmPrompt, promptInput } from '../utils/prompt.js';
+/**
+ * Double confirmation for account deletion: a yes/No confirm followed by
+ * typing the exact word DELETE. Throws AbortedError when either step fails.
+ * Skipped entirely when `yes` is true (for scripting via --yes).
+ */
+export async function confirmAccountDeletion(yes, deps = { confirm: confirmPrompt, promptInput }) {
+    if (yes)
+        return;
+    const proceed = await deps.confirm('This permanently deletes your ClipUGC account and all characters/videos. Continue?');
+    if (!proceed) {
+        throw new AbortedError('Account deletion aborted.');
+    }
+    const typed = await deps.promptInput('Type DELETE to confirm: ');
+    if (typed !== 'DELETE') {
+        throw new AbortedError('Account deletion aborted (confirmation text did not match).');
+    }
+}
+export function registerAccountCommands(program) {
+    const account = program
+        .command('account')
+        .description('Manage your ClipUGC account');
+    account
+        .command('delete')
+        .description('Permanently delete your ClipUGC account and all its characters and videos (irreversible)')
+        .option('--yes', 'Skip both confirmation prompts (for scripting)')
+        .action(async (options, cmd) => {
+        await confirmAccountDeletion(Boolean(options.yes));
+        const api = await createApiClient();
+        await deleteAccount(api);
+        const config = await loadConfig();
+        config.apiKey = '';
+        config.email = '';
+        await saveConfig(config);
+        if (isJsonMode(cmd)) {
+            printJson({ deleted: true });
+            return;
+        }
+        logger.success('Your ClipUGC account has been deleted and the stored API key removed.');
+    });
+}
+//# sourceMappingURL=account.js.map

package/dist/commands/account.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account.js","sourceRoot":"","sources":["../../src/commands/account.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAO3E;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,GAAY,EACZ,OAAoB,EAAE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE;IAE3D,IAAI,GAAG;QAAE,OAAO;IAEhB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAChC,oFAAoF,CACrF,CAAC;IACF,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,YAAY,CAAC,2BAA2B,CAAC,CAAC;IACtD,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,0BAA0B,CAAC,CAAC;IACjE,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvB,MAAM,IAAI,YAAY,CAAC,6DAA6D,CAAC,CAAC;IACxF,CAAC;AACH,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,OAAgB;IACtD,MAAM,OAAO,GAAG,OAAO;SACpB,OAAO,CAAC,SAAS,CAAC;SAClB,WAAW,CAAC,6BAA6B,CAAC,CAAC;IAE9C,OAAO;SACJ,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,0FAA0F,CAAC;SACvG,MAAM,CAAC,OAAO,EAAE,gDAAgD,CAAC;SACjE,MAAM,CAAC,KAAK,EAAE,OAA0B,EAAE,GAAY,EAAE,EAAE;QACzD,MAAM,sBAAsB,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;QAEnD,MAAM,GAAG,GAAG,MAAM,eAAe,EAAE,CAAC;QACpC,MAAM,aAAa,CAAC,GAAG,CAAC,CAAC;QAEzB,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;QAClC,MAAM,CAAC,MAAM,GAAG,EAAE,CAAC;QACnB,MAAM,CAAC,KAAK,GAAG,EAAE,CAAC;QAClB,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC;QAEzB,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,SAAS,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YAC7B,OAAO;QACT,CAAC;QACD,MAAM,CAAC,OAAO,CAAC,uEAAuE,CAAC,CAAC;IAC1F,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/commands/auth.d.ts

@@ -0,0 +1,14 @@
+import type { Command } from 'commander';
+import { type UserProfile } from '../services/user.service.js';
+/** Mask an API key for display: first 4 chars + ellipsis. */
+export declare function maskApiKey(apiKey: string): string;
+/**
+ * Validate an API key against GET /user and persist apiKey + email in config.
+ * Throws AuthError (with a key-specific message) when the key is rejected.
+ */
+export declare function performLogin(apiKey: string): Promise<UserProfile>;
+/** Remove the stored apiKey + email from the config file. Idempotent. */
+export declare function performLogout(): Promise<void>;
+/** Print a user profile as key/value lines, skipping null/empty fields. */
+export declare function printUserProfile(user: UserProfile): void;
+export declare function registerAuthCommands(program: Command): void;

package/dist/commands/auth.js

@@ -0,0 +1,152 @@
+import { createApiClient } from '../services/api.js';
+import { getUser } from '../services/user.service.js';
+import { getConfigPath, loadConfig, resolveApiBaseUrl, resolveApiKey, saveConfig } from '../utils/config.js';
+import { AuthError, ValidationError } from '../utils/errors.js';
+import { logger } from '../utils/logger.js';
+import { isJsonMode, printJson } from '../utils/output.js';
+import { promptSecret } from '../utils/prompt.js';
+const DASHBOARD_URL = 'https://clipugc.com/dashboard';
+/** Mask an API key for display: first 4 chars + ellipsis. */
+export function maskApiKey(apiKey) {
+    if (!apiKey)
+        return '';
+    return `${apiKey.slice(0, 4)}…`;
+}
+/**
+ * Validate an API key against GET /user and persist apiKey + email in config.
+ * Throws AuthError (with a key-specific message) when the key is rejected.
+ */
+export async function performLogin(apiKey) {
+    if (!apiKey) {
+        throw new ValidationError(`No API key provided. Create one in your ClipUGC dashboard at ${DASHBOARD_URL}.`);
+    }
+    const api = await createApiClient({ apiKey });
+    let user;
+    try {
+        user = await getUser(api);
+    }
+    catch (error) {
+        if (error instanceof AuthError) {
+            throw new AuthError(`That API key is invalid or has been revoked. Create a new one in your ClipUGC dashboard at ${DASHBOARD_URL} and try again.`);
+        }
+        throw error;
+    }
+    const config = await loadConfig();
+    config.apiKey = apiKey;
+    config.email = typeof user.email === 'string' ? user.email : '';
+    await saveConfig(config);
+    return user;
+}
+/** Remove the stored apiKey + email from the config file. Idempotent. */
+export async function performLogout() {
+    const config = await loadConfig();
+    config.apiKey = '';
+    config.email = '';
+    await saveConfig(config);
+}
+/** Print a user profile as key/value lines, skipping null/empty fields. */
+export function printUserProfile(user) {
+    for (const [key, value] of Object.entries(user)) {
+        if (value === null || value === undefined || value === '')
+            continue;
+        const rendered = typeof value === 'object' ? JSON.stringify(value) : String(value);
+        logger.kv(key, rendered);
+    }
+}
+export function registerAuthCommands(program) {
+    const auth = program
+        .command('auth')
+        .description('Log in and out of ClipUGC and inspect authentication status');
+    auth
+        .command('login')
+        .description(`Log in with an API key (create one in your ClipUGC dashboard at ${DASHBOARD_URL})`)
+        .option('--api-key <key>', 'API key from your ClipUGC dashboard (prompted securely if omitted)')
+        .action(async (options, cmd) => {
+        const json = isJsonMode(cmd);
+        let apiKey = options.apiKey;
+        if (!apiKey) {
+            if (!json) {
+                logger.info(`Create an API key in the ClipUGC dashboard at ${DASHBOARD_URL}`);
+            }
+            apiKey = await promptSecret('API key: ');
+        }
+        const user = await performLogin(apiKey);
+        const email = typeof user.email === 'string' && user.email ? user.email : null;
+        if (json) {
+            printJson({ authenticated: true, email });
+            return;
+        }
+        logger.success(`Logged in as ${email ?? 'unknown user'}`);
+        logger.hint('Try: clipugc characters list');
+    });
+    auth
+        .command('status')
+        .description('Show the config file, API base URL, and whether the stored API key is valid')
+        .action(async (_options, cmd) => {
+        const json = isJsonMode(cmd);
+        const config = await loadConfig();
+        const apiBaseUrl = await resolveApiBaseUrl();
+        const apiKey = await resolveApiKey();
+        if (!apiKey) {
+            if (json) {
+                printJson({ authenticated: false, email: null, apiBaseUrl });
+                return;
+            }
+            logger.kv('Config file', getConfigPath());
+            logger.kv('API base URL', apiBaseUrl);
+            logger.kv('API key', null);
+            logger.info('Not logged in. Run `clipugc auth login`.');
+            return;
+        }
+        let authenticated = false;
+        let email = config.email || null;
+        try {
+            const api = await createApiClient({ apiKey });
+            const user = await getUser(api);
+            authenticated = true;
+            if (typeof user.email === 'string' && user.email)
+                email = user.email;
+        }
+        catch (error) {
+            if (!(error instanceof AuthError))
+                throw error;
+        }
+        if (json) {
+            printJson({ authenticated, email: authenticated ? email : null, apiBaseUrl });
+            return;
+        }
+        logger.kv('Config file', getConfigPath());
+        logger.kv('API base URL', apiBaseUrl);
+        logger.kv('API key', maskApiKey(apiKey));
+        if (authenticated) {
+            logger.success(`authenticated as ${email ?? 'unknown user'}`);
+        }
+        else {
+            logger.warn('key invalid — run `clipugc auth login` with a fresh key');
+        }
+    });
+    auth
+        .command('logout')
+        .description('Remove the stored API key from the config file')
+        .action(async (_options, cmd) => {
+        await performLogout();
+        if (isJsonMode(cmd)) {
+            printJson({ loggedOut: true });
+            return;
+        }
+        logger.success(`Logged out. API key removed from ${getConfigPath()}`);
+    });
+    program
+        .command('whoami')
+        .description('Show the profile of the authenticated user')
+        .action(async (_options, cmd) => {
+        const api = await createApiClient();
+        const user = await getUser(api);
+        if (isJsonMode(cmd)) {
+            printJson(user);
+            return;
+        }
+        printUserProfile(user);
+    });
+}
+//# sourceMappingURL=auth.js.map

package/dist/commands/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAoB,MAAM,6BAA6B,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,iBAAiB,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC7G,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,aAAa,GAAG,+BAA+B,CAAC;AAEtD,6DAA6D;AAC7D,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IACvB,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC;AAClC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAc;IAC/C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,eAAe,CAAC,gEAAgE,aAAa,GAAG,CAAC,CAAC;IAC9G,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IAE9C,IAAI,IAAiB,CAAC;IACtB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,SAAS,EAAE,CAAC;YAC/B,MAAM,IAAI,SAAS,CACjB,8FAA8F,aAAa,iBAAiB,CAC7H,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;IAClC,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,MAAM,CAAC,KAAK,GAAG,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAChE,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC;IAEzB,OAAO,IAAI,CAAC;AACd,CAAC;AAED,yEAAyE;AACzE,MAAM,CAAC,KAAK,UAAU,aAAa;IACjC,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;IAClC,MAAM,CAAC,MAAM,GAAG,EAAE,CAAC;IACnB,MAAM,CAAC,KAAK,GAAG,EAAE,CAAC;IAClB,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC;AAC3B,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,gBAAgB,CAAC,IAAiB;IAChD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE;YAAE,SAAS;QACpE,MAAM,QAAQ,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACnF,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,OAAgB;IACnD,MAAM,IAAI,GAAG,OAAO;SACjB,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CAAC,6DAA6D,CAAC,CAAC;IAE9E,IAAI;SACD,OAAO,CAAC,OAAO,CAAC;SAChB,WAAW,CAAC,mEAAmE,aAAa,GAAG,CAAC;SAChG,MAAM,CAAC,iBAAiB,EAAE,oEAAoE,CAAC;SAC/F,MAAM,CAAC,KAAK,EAAE,OAA4B,EAAE,GAAY,EAAE,EAAE;QAC3D,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;QAE7B,IAAI,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,MAAM,CAAC,IAAI,CAAC,iDAAiD,aAAa,EAAE,CAAC,CAAC;YAChF,CAAC;YACD,MAAM,GAAG,MAAM,YAAY,CAAC,WAAW,CAAC,CAAC;QAC3C,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,MAAM,CAAC,CAAC;QACxC,MAAM,KAAK,GAAG,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;QAE/E,IAAI,IAAI,EAAE,CAAC;YACT,SAAS,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YAC1C,OAAO;QACT,CAAC;QACD,MAAM,CAAC,OAAO,CAAC,gBAAgB,KAAK,IAAI,cAAc,EAAE,CAAC,CAAC;QAC1D,MAAM,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEL,IAAI;SACD,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,6EAA6E,CAAC;SAC1F,MAAM,CAAC,KAAK,EAAE,QAA+B,EAAE,GAAY,EAAE,EAAE;QAC9D,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;QAC7B,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;QAClC,MAAM,UAAU,GAAG,MAAM,iBAAiB,EAAE,CAAC;QAC7C,MAAM,MAAM,GAAG,MAAM,aAAa,EAAE,CAAC;QAErC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,IAAI,IAAI,EAAE,CAAC;gBACT,SAAS,CAAC,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;gBAC7D,OAAO;YACT,CAAC;YACD,MAAM,CAAC,EAAE,CAAC,aAAa,EAAE,aAAa,EAAE,CAAC,CAAC;YAC1C,MAAM,CAAC,EAAE,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC;YACtC,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;YAC3B,MAAM,CAAC,IAAI,CAAC,0CAA0C,CAAC,CAAC;YACxD,OAAO;QACT,CAAC;QAED,IAAI,aAAa,GAAG,KAAK,CAAC;QAC1B,IAAI,KAAK,GAAkB,MAAM,CAAC,KAAK,IAAI,IAAI,CAAC;QAChD,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;YAC9C,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;YAChC,aAAa,GAAG,IAAI,CAAC;YACrB,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,IAAI,CAAC,KAAK;gBAAE,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACvE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,CAAC,KAAK,YAAY,SAAS,CAAC;gBAAE,MAAM,KAAK,CAAC;QACjD,CAAC;QAED,IAAI,IAAI,EAAE,CAAC;YACT,SAAS,CAAC,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;YAC9E,OAAO;QACT,CAAC;QAED,MAAM,CAAC,EAAE,CAAC,aAAa,EAAE,aAAa,EAAE,CAAC,CAAC;QAC1C,MAAM,CAAC,EAAE,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC;QACtC,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;QACzC,IAAI,aAAa,EAAE,CAAC;YAClB,MAAM,CAAC,OAAO,CAAC,oBAAoB,KAAK,IAAI,cAAc,EAAE,CAAC,CAAC;QAChE,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,IAAI,CAAC,yDAAyD,CAAC,CAAC;QACzE,CAAC;IACH,CAAC,CAAC,CAAC;IAEL,IAAI;SACD,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,gDAAgD,CAAC;SAC7D,MAAM,CAAC,KAAK,EAAE,QAA+B,EAAE,GAAY,EAAE,EAAE;QAC9D,MAAM,aAAa,EAAE,CAAC;QACtB,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,SAAS,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/B,OAAO;QACT,CAAC;QACD,MAAM,CAAC,OAAO,CAAC,oCAAoC,aAAa,EAAE,EAAE,CAAC,CAAC;IACxE,CAAC,CAAC,CAAC;IAEL,OAAO;SACJ,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,4CAA4C,CAAC;SACzD,MAAM,CAAC,KAAK,EAAE,QAA+B,EAAE,GAAY,EAAE,EAAE;QAC9D,MAAM,GAAG,GAAG,MAAM,eAAe,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,SAAS,CAAC,IAAI,CAAC,CAAC;YAChB,OAAO;QACT,CAAC;QACD,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/commands/characters.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+/** Register the `clipugc characters` command group (AI characters CRUD). */
+export declare function registerCharactersCommands(program: Command): void;