@cliptude/cli 0.1.19 → 0.1.30

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -17,6 +17,27 @@ pip install -e .
17
17
  cliptude auth login
18
18
  ```
19
19
 
20
+ ## Cliptude desktop app
21
+
22
+ The desktop app ships this CLI and MCP server, so nothing needs installing: in the app, open
23
+ **Settings → Connect an AI assistant** and click **Add** for Claude Desktop or Cursor, or copy the
24
+ command for Claude Code or Codex. Videos are then made in the app with your own provider keys.
25
+ ChatGPT only connects to servers on the internet, so it uses cliptude.com.
26
+
27
+ Where the CLI and MCP send jobs:
28
+
29
+ | | |
30
+ |---|---|
31
+ | `cliptude use desktop` | the running desktop app (fails with "Open Cliptude" when it is closed) |
32
+ | `cliptude use cloud` | cliptude.com |
33
+ | `cliptude use auto` (default) | the desktop app while it is running, else cliptude.com |
34
+ | `cliptude use` | show where jobs go now |
35
+
36
+ `CLIPTUDE_TARGET` overrides the saved choice, and `CLIPTUDE_BASE_URL` overrides both. The app's port
37
+ changes every launch: the CLI reads it from `desktop-runtime.json` and its key from `local-api.json`
38
+ in the app's data folder. The desktop gets only that local key and cliptude.com only your cliptude.com
39
+ login. A `CLIPTUDE_API_KEY` in the environment, without `CLIPTUDE_TARGET`, means cliptude.com.
40
+
20
41
  ## Commands
21
42
 
22
43
  ```bash
@@ -54,7 +75,13 @@ To revise a finished video, `editor` opens its timeline (item ids, times, text),
54
75
  On Faceless Documentary, Faceless Top 10, Avatar Video and Vector Explainer templates an agent can plan every visual and leave Cliptude
55
76
  only the voicing, sourcing and rendering:
56
77
 
57
- 1. `cliptude plan-job` (stops at `plan_ready`), `cliptude narration <job>`.
78
+ 1. `cliptude plan-job` (stops at `plan_ready`), `cliptude narration <job>`. Like every job, it answers first with a
79
+ review of its settings; music, sound effects, transitions, animations and web sources are on by default, and any the
80
+ template turns off (`no_music`, `no_sound_effects`, `no_transitions`, `no_motion_graphics`, ...) need the user's
81
+ approval in `--acknowledge`.
82
+ Your own footage: `cliptude upload-media <job> trailer.mp4 --split-shots` cuts a whole source into checked 3-12 s
83
+ clips on its cuts and prints their keep ids; each upload's notes say what the build review would report (a
84
+ watermark, an end screen, captions).
58
85
  2. `cliptude catalog --compact`, then `--types a,b` for full entries (`--premium` lists only the premium boards).
59
86
  3. `cliptude plan-check <job> plan.json` until valid, `cliptude plan-lock <job> plan.json`, `cliptude continue <job>`.
60
87
  The job stops at `ready_for_edit`: built and charged, not rendered.
@@ -64,11 +91,14 @@ only the voicing, sourcing and rendering:
64
91
  media reused, nothing more charged.
65
92
  6. Render once: `cliptude editor <job>`, `cliptude render <project> --wait`.
66
93
 
94
+ Aim for two builds: one to review, one to ship. The skill's "One pass" section has the order of work (footage budget,
95
+ sources split by shot, people's photos first, picture assignment by script, person-card caps).
96
+
67
97
  MCP tools: `create_plan_job`, `get_narration`, `get_kind_catalog`, `check_plan`, `lock_plan`, `get_plan`,
68
98
  `continue_job`, `get_plan_review`, `get_plan_report`, then `open_editor_project` and `render_project`.
69
99
  The plan sets the look (theme, style, colours, music), every graphic with its own data, colours and sound, the
70
100
  footage under every beat, the transition on each cut, two-image reveals, and free sound effects; `get_kind_catalog`
71
- lists the graphics, `transitions`, `reveal_styles` and `sounds` (with previews). The plan schema and rules are in
101
+ lists the graphics, `transitions`, `reveal_styles`, `clip_effects` and `sounds` (with previews). The plan schema and rules are in
72
102
  `skills/cliptude-plan/SKILL.md`. The job costs the same as the website price.
73
103
 
74
104
  ### Product videos from a store
@@ -0,0 +1,311 @@
1
+ """MCP Apps (interactive widgets) for hosts that render them: Claude Desktop, claude.ai.
2
+
3
+ Spec: https://modelcontextprotocol.io/specification/draft/extensions/apps (SEP-1865, `io.modelcontextprotocol/ui`).
4
+
5
+ Each widget is a `ui://cliptude/...` HTML resource (served as `text/html;profile=mcp-app`) that the host shows in a
6
+ sandboxed iframe next to a tool's result:
7
+
8
+ - list_avatars -> ui://cliptude/avatars.html avatar thumbnails, pick one
9
+ - list_voices -> ui://cliptude/voices.html play voice previews, pick one
10
+ - list_vector_characters -> ui://cliptude/characters.html Vector Explainer cast and uploads, pick one
11
+ - get_render, get_product_video_status, show_video
12
+ -> ui://cliptude/player.html watch the MP4, or "not rendered yet"
13
+ - show_choices -> ui://cliptude/choices.html music (play), backgrounds, style packs, themes, captions
14
+ - show_publish_kit -> ui://cliptude/publish-kit.html thumbnails, title ideas, description, chapters, tags
15
+
16
+ The existing tools keep their names, parameters and JSON (the text content stays the same for clients without
17
+ Apps); only `_meta.ui.resourceUri` is added to them (`bind_existing_tools`). show_choices, show_video and
18
+ show_publish_kit are new, thin tools: binding a widget to get_template_options, get_job or the editor-project
19
+ tools would draw a widget on every one of their (frequent, polling) calls.
20
+
21
+ A widget picks by posting a `ui/message` into the chat ("Use the voice ... (voice_id ...)"), so the model gets the
22
+ id without the user typing it. The avatar and voice pickers can also make new ones in the chat (create_avatar,
23
+ design_voice_previews / save_designed_voice, clone_voice in creation.py), calling those tools with `tools/call`.
24
+ """
25
+
26
+ from __future__ import annotations
27
+
28
+ from collections.abc import Callable
29
+ from importlib import resources
30
+ from typing import Annotated, Any
31
+
32
+ from pydantic import Field
33
+
34
+ try: # mcp >= 2.3 ships the Apps extension; older SDKs simply serve no widgets.
35
+ from mcp.server.apps import APP_MIME_TYPE, Apps, ResourceCsp, ResourcePermissions
36
+ except ImportError: # pragma: no cover - exercised only on an old SDK
37
+ Apps = None # type: ignore[assignment,misc]
38
+ APP_MIME_TYPE = "text/html;profile=mcp-app"
39
+ ResourceCsp = ResourcePermissions = None # type: ignore[assignment,misc]
40
+
41
+ AVATARS_URI = "ui://cliptude/avatars.html"
42
+ VOICES_URI = "ui://cliptude/voices.html"
43
+ CHARACTERS_URI = "ui://cliptude/characters.html"
44
+ PLAYER_URI = "ui://cliptude/player.html"
45
+ CHOICES_URI = "ui://cliptude/choices.html"
46
+ PUBLISH_KIT_URI = "ui://cliptude/publish-kit.html"
47
+
48
+ # uri -> (file, name, description)
49
+ WIDGETS: dict[str, tuple[str, str, str]] = {
50
+ AVATARS_URI: ("avatars.html", "Avatar picker", "Avatar thumbnails to pick the presenter of an Avatar Video."),
51
+ VOICES_URI: ("voices.html", "Voice picker", "Voice previews to listen to and pick a narration voice."),
52
+ CHARACTERS_URI: ("characters.html", "Character picker", "Vector Explainer characters to pick from."),
53
+ PLAYER_URI: ("player.html", "Video player", "Plays a finished Cliptude MP4, or shows that it is not rendered yet."),
54
+ CHOICES_URI: ("choices.html", "Setting picker", "Previews of music, backgrounds and styles to pick a template setting."),
55
+ PUBLISH_KIT_URI: ("publish-kit.html", "Publish kit", "Thumbnails, title ideas, description, chapters and tags."),
56
+ }
57
+
58
+ # Existing tools that get a widget, by name.
59
+ BOUND_TOOLS: dict[str, str] = {
60
+ "list_avatars": AVATARS_URI,
61
+ "list_voices": VOICES_URI,
62
+ "list_vector_characters": CHARACTERS_URI,
63
+ "get_render": PLAYER_URI,
64
+ "get_product_video_status": PLAYER_URI,
65
+ }
66
+
67
+ # Where the widgets' pictures, audio and video come from (CSP img-src/media-src via resourceDomains).
68
+ MEDIA_DOMAINS: tuple[str, ...] = (
69
+ # Avatar previews (videos/avatar_preview.py: HeyGen thumbnails proxied and signed, because HeyGen's own
70
+ # files2.heygen.ai links answer 403 to browsers), built-in Vector characters (/static/vector_explainer/),
71
+ # uploaded characters (/media/), library music (/static/music/), thumbnails not yet on the CDN (/media/).
72
+ "https://cliptude.com",
73
+ "https://www.cliptude.com",
74
+ # Public R2 bucket: library background thumbnails, generated thumbnails, uploaded backgrounds, samples.
75
+ "https://cdn.cliptude.com",
76
+ # Signed MP4 links of finished videos and editor renders (private R2 bucket, videos/r2_storage.py).
77
+ "https://*.r2.cloudflarestorage.com",
78
+ # Voice previews: ElevenLabs (shared-library previews on storage.googleapis.com/eleven-public-prod and the
79
+ # API host), Cartesia (preview_file_url), Voicetory (preview_audio). MiniMax and Inworld have none.
80
+ "https://storage.googleapis.com",
81
+ "https://api.us.elevenlabs.io",
82
+ "https://api.elevenlabs.io",
83
+ "https://files.cartesia.ai",
84
+ "https://voicetory.com",
85
+ )
86
+ # The Desktop app serves its own media on a random localhost port (stdio MCP only).
87
+ LOCAL_MEDIA_DOMAINS: tuple[str, ...] = ("http://127.0.0.1:*", "http://localhost:*")
88
+
89
+ # show_choices: field -> (kind the widget draws, heading)
90
+ CHOICE_FIELDS: dict[str, tuple[str, str]] = {
91
+ "background_music_library_file": ("music", "Background music"),
92
+ "background_image": ("image", "Background"),
93
+ "faceless_documentary_style": ("style", "Style pack"),
94
+ "visual_theme": ("theme", "Visual theme"),
95
+ "caption_style": ("caption", "Caption style"),
96
+ "vector_illustration_style": ("text", "Illustration style"),
97
+ "vector_reveal_mode": ("text", "Motion"),
98
+ }
99
+ # Fields an agent-planned video also sets in its plan's look.
100
+ _PLAN_LOOK_FIELDS = frozenset({"background_music_library_file", "visual_theme", "faceless_documentary_style"})
101
+
102
+
103
+ def _permissions() -> dict[str, Any]:
104
+ if ResourcePermissions is None:
105
+ return {}
106
+ return {
107
+ # Copy buttons (titles, description, tags) use the Clipboard API.
108
+ PUBLISH_KIT_URI: ResourcePermissions(clipboard_write={}),
109
+ # "Clone a voice" can record a sample in the widget; uploading a file works without it.
110
+ VOICES_URI: ResourcePermissions(microphone={}),
111
+ }
112
+
113
+
114
+ _PERMISSIONS = _permissions()
115
+
116
+
117
+ def apps_available() -> bool:
118
+ return Apps is not None
119
+
120
+
121
+ def widget_html(file_name: str) -> str:
122
+ """A widget's HTML with the shared bridge and stylesheet inlined (no external script or style)."""
123
+ pkg = resources.files("cliptude_mcp") / "widgets"
124
+ html = (pkg / file_name).read_text(encoding="utf-8")
125
+ bridge = (pkg / "bridge.js").read_text(encoding="utf-8")
126
+ css = (pkg / "base.css").read_text(encoding="utf-8")
127
+ return html.replace("/*@BASE_CSS@*/", css).replace("/*@BRIDGE_JS@*/", bridge)
128
+
129
+
130
+ def media_domains(*, local: bool) -> list[str]:
131
+ return list(MEDIA_DOMAINS) + (list(LOCAL_MEDIA_DOMAINS) if local else [])
132
+
133
+
134
+ def _ui_meta(uri: str) -> dict[str, Any]:
135
+ # `ui.resourceUri` is the spec's key; the flat `ui/resourceUri` is its deprecated form, kept for hosts that
136
+ # shipped before the rename.
137
+ return {"ui": {"resourceUri": uri}, "ui/resourceUri": uri}
138
+
139
+
140
+ def build_apps(
141
+ client: Callable[[], Any],
142
+ err: Callable[[Exception], dict[str, Any]],
143
+ *,
144
+ local: bool,
145
+ ):
146
+ """The Apps extension with every widget resource and the new show_* tools; None on an SDK without Apps."""
147
+ if Apps is None:
148
+ return None
149
+ from mcp.types import ToolAnnotations
150
+
151
+ apps = Apps()
152
+ csp = ResourceCsp(resource_domains=media_domains(local=local))
153
+ for uri, (file_name, name, description) in WIDGETS.items():
154
+ apps.add_html_resource(
155
+ uri,
156
+ widget_html(file_name),
157
+ name=name,
158
+ title=name,
159
+ description=description,
160
+ csp=csp,
161
+ permissions=_PERMISSIONS.get(uri),
162
+ prefers_border=True,
163
+ )
164
+
165
+ @apps.tool(
166
+ resource_uri=CHOICES_URI,
167
+ meta={"ui/resourceUri": CHOICES_URI},
168
+ name="show_choices",
169
+ title="Show setting choices",
170
+ annotations=ToolAnnotations(title="Show setting choices", read_only_hint=True, open_world_hint=False),
171
+ )
172
+ def show_choices(
173
+ format: Annotated[str, Field(description="Video format, e.g. faceless_documentary or vector_explainer")],
174
+ field: Annotated[
175
+ str,
176
+ Field(description="Setting to choose: " + ", ".join(CHOICE_FIELDS)),
177
+ ],
178
+ ) -> dict[str, Any]:
179
+ """Let the user preview and pick one template setting: background music (play each track), background picture, style pack (colour swatches), visual theme, caption style, or the Vector Explainer illustration style / motion. In hosts that show apps the user picks in a widget and the choice arrives as their message; otherwise read choices and ask. Returns {field, choices:[{value, label, ...preview links}], default, usage}."""
180
+ field = (field or "").strip()
181
+ if field not in CHOICE_FIELDS:
182
+ return {"error": f"field must be one of: {', '.join(CHOICE_FIELDS)}"}
183
+ try:
184
+ options = client().template_options(format)
185
+ except Exception as exc:
186
+ return err(exc)
187
+ return choices_payload(options, format, field)
188
+
189
+ @apps.tool(
190
+ resource_uri=PLAYER_URI,
191
+ meta={"ui/resourceUri": PLAYER_URI},
192
+ name="show_video",
193
+ title="Show video",
194
+ annotations=ToolAnnotations(title="Show video", read_only_hint=True, open_world_hint=False),
195
+ )
196
+ def show_video(
197
+ job_id: Annotated[str, Field(min_length=8, description="Job / video UUID")],
198
+ ) -> dict[str, Any]:
199
+ """Show a finished job's MP4 in a player the user can watch in the chat (hosts that show apps), with an open link. For an edited video, get_render shows its export the same way. Returns {job_id, title, status, url}; url is empty until the video is ready."""
200
+ try:
201
+ job = client().get_job(job_id)
202
+ except Exception as exc:
203
+ return err(exc)
204
+ return video_payload(job, job_id)
205
+
206
+ @apps.tool(
207
+ resource_uri=PUBLISH_KIT_URI,
208
+ meta={"ui/resourceUri": PUBLISH_KIT_URI},
209
+ name="show_publish_kit",
210
+ title="Show publish kit",
211
+ annotations=ToolAnnotations(title="Show publish kit", read_only_hint=False, destructive_hint=False, open_world_hint=False),
212
+ )
213
+ def show_publish_kit(
214
+ job_id: Annotated[str, Field(min_length=8, description="Completed video job id")],
215
+ ) -> dict[str, Any]:
216
+ """The generated thumbnails, title ideas, YouTube description, chapters and tags of a finished video, shown as a publish kit with copy buttons (hosts that show apps). Opens the video's editor project like open_editor_project. Returns {job_id, project_id, title, thumbnails, publish_metadata}."""
217
+ try:
218
+ data = client().open_editor_project(job_id)
219
+ except Exception as exc:
220
+ return err(exc)
221
+ return publish_kit_payload(data, job_id)
222
+
223
+ return apps
224
+
225
+
226
+ def bind_existing_tools(mcp: Any) -> list[str]:
227
+ """Stamp `_meta.ui.resourceUri` on the existing tools that have a widget; returns the names bound.
228
+
229
+ The tools are registered by server.py as before, so their names, parameters and results do not change.
230
+ """
231
+ manager = getattr(mcp, "_tool_manager", None)
232
+ bound = []
233
+ for name, uri in BOUND_TOOLS.items():
234
+ tool = manager.get_tool(name) if manager is not None else None
235
+ if tool is None:
236
+ continue
237
+ tool.meta = {**(tool.meta or {}), **_ui_meta(uri)}
238
+ bound.append(name)
239
+ return bound
240
+
241
+
242
+ def choices_payload(options: Any, format_value: str, field: str) -> dict[str, Any]:
243
+ kind, label = CHOICE_FIELDS[field]
244
+ if not isinstance(options, dict):
245
+ return {"error": "Cliptude returned no template options."}
246
+ if options.get("error"):
247
+ return options
248
+ entry = (options.get("fields") or {}).get(field)
249
+ if not isinstance(entry, dict):
250
+ return {"error": f"{format_value} templates have no {field} setting."}
251
+ details = entry.get("choice_details")
252
+ if not isinstance(details, list): # An older Cliptude server: values only.
253
+ details = [{"value": value, "label": str(value)} for value in entry.get("choices") or []]
254
+ usage = f"Set {field} in create_template settings"
255
+ usage += " (or in the plan's look on an agent-planned video)." if field in _PLAN_LOOK_FIELDS else "."
256
+ if field == "background_music_library_file":
257
+ usage += " With it, set background_music_mode to library; none means no music."
258
+ return {
259
+ "format": format_value,
260
+ "field": field,
261
+ "kind": kind,
262
+ "label": label,
263
+ "description": entry.get("description") or entry.get("note") or "",
264
+ "default": entry.get("default"),
265
+ "current": entry.get("default"),
266
+ "choices": details,
267
+ "usage": usage,
268
+ }
269
+
270
+
271
+ def video_payload(job: Any, job_id: str) -> dict[str, Any]:
272
+ if not isinstance(job, dict):
273
+ return {"error": "Cliptude returned no job."}
274
+ if job.get("error") and not job.get("status"):
275
+ return job
276
+ output = job.get("output") if isinstance(job.get("output"), dict) else {}
277
+ return {
278
+ "job_id": str(job.get("id") or job.get("job_id") or job_id),
279
+ "title": job.get("title") or "",
280
+ "status": job.get("status") or "",
281
+ "progress": job.get("progress"),
282
+ "current_step": job.get("current_step") or "",
283
+ "error": job.get("error") or "",
284
+ "url": output.get("url") or "",
285
+ "path": output.get("path") or "",
286
+ "note": (
287
+ "Saved on this computer: open path." if output.get("path") and not output.get("url") else ""
288
+ ),
289
+ }
290
+
291
+
292
+ def publish_kit_payload(data: Any, job_id: str) -> dict[str, Any]:
293
+ if not isinstance(data, dict):
294
+ return {"error": "Cliptude returned no editor project."}
295
+ if data.get("error"):
296
+ return data
297
+ project = data.get("project") if isinstance(data.get("project"), dict) else data
298
+ meta = project.get("publish_metadata") if isinstance(project.get("publish_metadata"), dict) else {}
299
+ return {
300
+ "job_id": job_id,
301
+ "project_id": project.get("id"),
302
+ "title": project.get("title") or "",
303
+ "thumbnails": project.get("thumbnails") or {"status": "", "items": []},
304
+ "publish_metadata": {
305
+ "title_variants": meta.get("title_variants") or [],
306
+ "description": meta.get("description") or "",
307
+ "chapters": meta.get("chapters") or "",
308
+ "tags": meta.get("tags") or [],
309
+ "downloads": meta.get("downloads") or {},
310
+ },
311
+ }
@@ -23,38 +23,55 @@ def _add_review_args(parser) -> None:
23
23
  )
24
24
 
25
25
 
26
- def _create_reviewed(client: CliptudeClient, args, **kwargs):
27
- """create_job behind the job review: in a terminal, show it and ask; otherwise print it and stop.
26
+ def _reviewed(args, call, *, heading: str = "Review this video before it is created:",
27
+ question: str = "Create this video?"):
28
+ """A call that spends credits, behind its review: in a terminal, show it and ask; otherwise print it and stop.
28
29
 
29
- Cliptude answers a job without a review_token with the review (HTTP 428) and creates nothing.
30
+ Cliptude answers create_job, continue, product script/render, agent and paid render without a review_token
31
+ with the review (HTTP 428) and does nothing. ``call(review_token, acknowledge)`` makes the request.
30
32
  """
31
33
  token = (getattr(args, "review_token", "") or "").strip() or None
32
34
  acks = [a.strip() for raw in (getattr(args, "acknowledge", None) or []) for a in raw.split(",") if a.strip()]
33
35
  try:
34
- return client.create_job(review_token=token, acknowledge=acks or None, **kwargs)
36
+ return call(token, acks or None)
35
37
  except CliptudeApiError as exc:
36
38
  detail = exc.payload if isinstance(exc.payload, dict) else {}
37
39
  if exc.status != 428 or "review" not in detail or not sys.stdin.isatty():
38
40
  raise
39
41
  review = detail["review"]
40
42
  out = sys.stderr
41
- out.write("\nReview this video before it is created:\n")
43
+ out.write(f"\n{heading}\n")
44
+ if review.get("summary"):
45
+ out.write(f" {review['summary']}\n")
42
46
  for item in review.get("settings") or []:
43
47
  out.write(f" {item.get('label')}: {item.get('value')}\n")
44
48
  credits = review.get("credits") or {}
45
49
  if credits.get("credits_required") is not None:
46
50
  out.write(f" Credits: about {credits['credits_required']} (you have {credits.get('credits_available')})\n")
51
+ else:
52
+ for key, value in credits.items():
53
+ out.write(f" Credits, {key.replace('_', ' ')}: {value}\n")
47
54
  for warning in review.get("warnings") or []:
48
55
  out.write(f" ! {warning}\n")
49
56
  approved = []
50
57
  for ack in review.get("acknowledgements_required") or []:
51
58
  out.write(f"\n {ack['message']}\n")
52
59
  if input(f" Approve ({ack['id']})? [y/N] ").strip().lower() != "y":
53
- raise CliptudeApiError("Not created: change the template and run again.")
60
+ raise CliptudeApiError("Not done: change the template and run again.")
54
61
  approved.append(ack["id"])
55
- if input("\nCreate this video? [y/N] ").strip().lower() != "y":
56
- raise CliptudeApiError("Not created.")
57
- return client.create_job(review_token=detail["review_token"], acknowledge=approved or None, **kwargs)
62
+ if input(f"\n{question} [y/N] ").strip().lower() != "y":
63
+ raise CliptudeApiError("Not done: nothing was spent.")
64
+ return call(detail["review_token"], approved or None)
65
+
66
+
67
+ def _create_reviewed(client: CliptudeClient, args, **kwargs):
68
+ """create_job behind the job review (see _reviewed)."""
69
+ return _reviewed(args, lambda token, acks: client.create_job(review_token=token, acknowledge=acks, **kwargs))
70
+
71
+
72
+ def _spend_reviewed(args, call, question: str):
73
+ """A call on an existing job or project that spends credits, behind its review (see _reviewed)."""
74
+ return _reviewed(args, lambda token, _acks: call(token), heading="This spends credits:", question=question)
58
75
 
59
76
 
60
77
  def _die(exc: Exception, code: int = 1) -> None:
@@ -87,8 +104,8 @@ def _add_thumbnail_args(parser: argparse.ArgumentParser, *, scope: str) -> None:
87
104
  "--thumbnail-reference",
88
105
  default="",
89
106
  help=(
90
- f"YouTube video link or https image whose thumbnail style {scope} copies. Without a brief or "
91
- "reference, each video picks a reference for its own title."
107
+ f"YouTube video link or https image whose thumbnail style {scope} copies. Videos need a brief or "
108
+ "reference (here, on the template, or when the job is continued); Cliptude does not guess one."
92
109
  ),
93
110
  )
94
111
 
@@ -174,6 +191,16 @@ def _run_auth(auth_cmd: str) -> None:
174
191
  clear_credentials()
175
192
  print("Logged out.")
176
193
  return
194
+ from cliptude_mcp.client import resolve_connection
195
+
196
+ conn = resolve_connection()
197
+ if conn["runtime"] == "desktop":
198
+ if conn["error"]:
199
+ print(conn["error"], file=sys.stderr)
200
+ raise SystemExit(1)
201
+ account = CliptudeClient(client_kind="cli").get_account()
202
+ print(f"Using the Cliptude desktop app as {account.get('email')} (no cliptude.com login needed).")
203
+ return
177
204
  if not stored_access_token():
178
205
  print("Not authenticated. Run: cliptude auth login", file=sys.stderr)
179
206
  raise SystemExit(1)
@@ -185,6 +212,19 @@ def _run_auth(auth_cmd: str) -> None:
185
212
  print(f"Logged in{f' as {email}' if email else '.'}")
186
213
 
187
214
 
215
+ def _run_use(target: str | None) -> None:
216
+ from cliptude_mcp.client import chosen_target, resolve_connection, save_target
217
+
218
+ if target:
219
+ save_target(target)
220
+ conn = resolve_connection()
221
+ where = {"desktop": "the Cliptude desktop app", "cloud": "cliptude.com"}.get(conn["runtime"], conn["base_url"])
222
+ print(f"Target: {chosen_target()} → {where}" + (f" ({conn['base_url']})" if conn["base_url"] else ""))
223
+ if conn["error"]:
224
+ print(conn["error"], file=sys.stderr)
225
+ raise SystemExit(1)
226
+
227
+
188
228
  def _review_arg(value: str) -> dict:
189
229
  """--review "quote|author|rating" -> {quote, author, rating}."""
190
230
  parts = [p.strip() for p in value.split("|")]
@@ -214,6 +254,13 @@ def main(argv: list[str] | None = None) -> None:
214
254
  auth_sub.add_parser("logout", help="Delete the local session")
215
255
  auth_sub.add_parser("status", help="Show whether this machine is signed in")
216
256
 
257
+ use = sub.add_parser(
258
+ "use",
259
+ help="Make videos in the Cliptude desktop app or on cliptude.com (no argument: show where)",
260
+ )
261
+ use.add_argument("target", nargs="?", choices=["desktop", "cloud", "auto"],
262
+ help="auto = the desktop app while it is running, else cliptude.com")
263
+
217
264
  t = sub.add_parser("templates", help="List saved templates")
218
265
  t.add_argument("--limit", type=int, default=20)
219
266
  t.add_argument("--offset", type=int, default=0)
@@ -378,6 +425,12 @@ def main(argv: list[str] | None = None) -> None:
378
425
  default=None,
379
426
  help="No scene transitions; hard cuts only. Omit to use the template.",
380
427
  )
428
+ g.add_argument(
429
+ "--disable-sound-effects",
430
+ action=argparse.BooleanOptionalAction,
431
+ default=None,
432
+ help="No sound effects; --no-disable-sound-effects turns them on for this video even if the template has them off. Omit to use the template.",
433
+ )
381
434
  g.add_argument(
382
435
  "--exclude-animation-type",
383
436
  action="append",
@@ -445,6 +498,8 @@ def main(argv: list[str] | None = None) -> None:
445
498
  ),
446
499
  )
447
500
  cont.add_argument("job_id")
501
+ _add_thumbnail_args(cont, scope="this video")
502
+ _add_review_args(cont)
448
503
 
449
504
  prod = sub.add_parser(
450
505
  "product",
@@ -472,9 +527,16 @@ def main(argv: list[str] | None = None) -> None:
472
527
  ps.add_argument("--cta-url", default="")
473
528
  ps.add_argument("--review", action="append", default=[],
474
529
  help='A real customer review, "quote|author|rating" (repeat up to 3 times)')
530
+ ps.add_argument("--script-file", default="",
531
+ help="Narration you wrote (text file); the job is script_ready at once. Omit to let Cliptude write it")
532
+ ps.add_argument("--plan", action="store_true",
533
+ help="You plan every visual: the job is voiced and stops at plan_ready (plan-check, plan-lock, then product render)")
534
+ _add_review_args(ps)
475
535
  pr = prod_sub.add_parser("render", help="Produce the video from a ready product script")
476
536
  pr.add_argument("job_id")
477
537
  pr.add_argument("--aspect-ratio", default="16:9")
538
+ _add_thumbnail_args(pr, scope="this video")
539
+ _add_review_args(pr)
478
540
  pst = prod_sub.add_parser("status", help="Stage, script, preview link and MP4 of a product video")
479
541
  pst.add_argument("job_id")
480
542
 
@@ -532,6 +594,8 @@ def main(argv: list[str] | None = None) -> None:
532
594
  um = sub.add_parser("upload-media", help="Send a picture or clip you found to a plan job; prints its keep id for media.keep")
533
595
  um.add_argument("job_id")
534
596
  um.add_argument("path", help="Local JPG/PNG/WEBP/GIF (up to 15 MB) or MP4/MOV/WEBM/M4V (up to 300 MB)")
597
+ um.add_argument("--split-shots", action="store_true",
598
+ help="Also cut a long source into 3-12 s clips on its cuts, each checked and kept (prints their keep ids)")
535
599
 
536
600
  ed = sub.add_parser("editor", help="Open the timeline editor project for a completed job (prints the timeline)")
537
601
  ed.add_argument("job_id")
@@ -553,6 +617,7 @@ def main(argv: list[str] | None = None) -> None:
553
617
  ag.add_argument("--tier", default="fast", help="fast or smart (see cliptude agent-tiers)")
554
618
  ag.add_argument("--chat", default="", help="Continue an existing agent chat id")
555
619
  ag.add_argument("--wait", action="store_true", help="Poll until the run finishes")
620
+ _add_review_args(ag)
556
621
 
557
622
  ags = sub.add_parser("agent-status", help="Get a Cliptude Agent run")
558
623
  ags.add_argument("project_id")
@@ -569,6 +634,7 @@ def main(argv: list[str] | None = None) -> None:
569
634
  rn.add_argument("--wait", action="store_true", help="Poll until the render finishes")
570
635
  rn.add_argument("--accept-quality-findings", action="store_true",
571
636
  help="Agent-planned jobs: render although plan-review still lists plan quality findings")
637
+ _add_review_args(rn)
572
638
 
573
639
  rs = sub.add_parser("render-status", help="Get an editor render (output_url when done)")
574
640
  rs.add_argument("render_id")
@@ -591,6 +657,9 @@ def main(argv: list[str] | None = None) -> None:
591
657
  if args.cmd == "auth":
592
658
  _run_auth(args.auth_cmd)
593
659
  return
660
+ if args.cmd == "use":
661
+ _run_use(args.target)
662
+ return
594
663
  client = CliptudeClient(client_kind="cli")
595
664
  try:
596
665
  if args.cmd == "templates":
@@ -685,6 +754,7 @@ def main(argv: list[str] | None = None) -> None:
685
754
  disable_overlays=args.disable_overlays,
686
755
  disable_effects=args.disable_effects,
687
756
  disable_transitions=args.disable_transitions,
757
+ disable_sound_effects=args.disable_sound_effects,
688
758
  excluded_animation_types=args.excluded_animation_types,
689
759
  excluded_transition_kinds=args.excluded_transition_kinds,
690
760
  thumbnail=_thumbnail_from_args(args),
@@ -762,25 +832,34 @@ def main(argv: list[str] | None = None) -> None:
762
832
  elif args.cmd == "plan-report":
763
833
  _print(client.get_plan_report(args.job_id))
764
834
  elif args.cmd == "upload-media":
765
- _print(client.upload_plan_media(args.job_id, args.path))
835
+ _print(client.upload_plan_media(args.job_id, args.path, split_shots=args.split_shots))
766
836
  elif args.cmd == "download-voiceover":
767
837
  dest = Path(args.out)
768
838
  client.download_voiceover_file(args.job_id, dest)
769
839
  _print({"ok": True, "path": str(dest.resolve())})
770
840
  elif args.cmd == "continue":
771
- _print(client.continue_job(args.job_id))
841
+ thumbnail = _thumbnail_from_args(args)
842
+ _print(_spend_reviewed(
843
+ args, lambda token: client.continue_job(args.job_id, thumbnail=thumbnail, review_token=token),
844
+ "Build this video?",
845
+ ))
772
846
  elif args.cmd == "product":
773
847
  if args.product_cmd == "fetch":
774
848
  _print(client.fetch_product_context(args.url_or_query, store_domain=args.store or None))
775
849
  elif args.product_cmd == "script":
776
850
  angle = int(args.angle) if str(args.angle).isdigit() else args.angle
777
- _print(client.draft_product_script(
851
+ script = Path(args.script_file).read_text(encoding="utf-8") if args.script_file else None
852
+ _print(_reviewed(args, lambda token, acks: client.draft_product_script(
778
853
  args.product_id, angle=angle, duration=args.duration, template_id=args.template or None,
779
854
  title=args.title or None, discount_code=args.discount_code or None, cta_url=args.cta_url or None,
780
- reviews=[_review_arg(r) for r in args.review] or None,
781
- ))
855
+ reviews=[_review_arg(r) for r in args.review] or None, script=script, plan=args.plan,
856
+ review_token=token, acknowledge=acks,
857
+ ), question="Start this product video?"))
782
858
  elif args.product_cmd == "render":
783
- _print(client.render_product_video(args.job_id, aspect_ratio=args.aspect_ratio))
859
+ thumbnail = _thumbnail_from_args(args)
860
+ _print(_spend_reviewed(args, lambda token: client.render_product_video(
861
+ args.job_id, aspect_ratio=args.aspect_ratio, thumbnail=thumbnail, review_token=token,
862
+ ), "Build this product video?"))
784
863
  else:
785
864
  _print(client.get_product_video_status(args.job_id))
786
865
  elif args.cmd == "editor":
@@ -792,9 +871,10 @@ def main(argv: list[str] | None = None) -> None:
792
871
  if not (prompt or "").strip():
793
872
  raise CliptudeApiError("Provide --prompt or --prompt-file.")
794
873
  items = [i.strip() for i in (args.items or "").split(",") if i.strip()]
795
- payload = client.run_agent(
796
- args.project_id, prompt=prompt, tier=args.tier, referenced_item_ids=items, chat_id=args.chat or None
797
- )
874
+ payload = _spend_reviewed(args, lambda token: client.run_agent(
875
+ args.project_id, prompt=prompt, tier=args.tier, referenced_item_ids=items, chat_id=args.chat or None,
876
+ review_token=token,
877
+ ), "Run the agent?")
798
878
  if args.wait:
799
879
  run_id = (payload.get("run") or {}).get("id")
800
880
  payload = _wait(lambda: client.get_agent_run(args.project_id, run_id), lambda p: (p.get("run") or {}).get("status"))
@@ -806,7 +886,9 @@ def main(argv: list[str] | None = None) -> None:
806
886
  elif args.cmd == "agent-tiers":
807
887
  _print(client.agent_tiers())
808
888
  elif args.cmd == "render":
809
- payload = client.render_project(args.project_id, accept_quality_findings=args.accept_quality_findings)
889
+ payload = _spend_reviewed(args, lambda token: client.render_project(
890
+ args.project_id, accept_quality_findings=args.accept_quality_findings, review_token=token,
891
+ ), "Render this MP4?")
810
892
  if args.wait:
811
893
  render_id = (payload.get("render") or {}).get("id")
812
894
  payload = _wait(lambda: client.get_render(render_id), lambda p: (p.get("render") or {}).get("status"))