@cliptude/cli 0.1.21 → 0.1.32

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.
@@ -1,4 +1,4 @@
1
- """Tiny CLI wrapping /api/v1: auth | templates | template-create | template-options | voices | avatars | estimate | generate | editor | agent | render | script | voiceover | continue | status | jobs | account | cancel."""
1
+ """Tiny CLI wrapping /api/v1: auth | pick | templates | template-create | template-options | voices | avatars | estimate | generate | editor | agent | render | script | voiceover | continue | status | jobs | account | cancel."""
2
2
 
3
3
  from __future__ import annotations
4
4
 
@@ -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
 
@@ -158,6 +175,43 @@ def _wait(fetch, status_of, *, interval: float = 10.0, timeout: float = 3600.0):
158
175
  time.sleep(interval)
159
176
 
160
177
 
178
+ def _run_pick(client: CliptudeClient, args) -> dict:
179
+ """Open a browser picker (made here with --kind, or one an agent got as browser_picker_url) and wait for it.
180
+
181
+ The page is the same widget Claude Desktop shows (avatars, voices, music, a review to confirm, ...), on
182
+ cliptude.com for the signed-in owner, for 15 minutes. Returns the pick once the user is done.
183
+ """
184
+ import time
185
+ import webbrowser
186
+
187
+ pick_id, url = (args.pick_id or "").strip(), (args.url or "").strip()
188
+ if args.kind:
189
+ try:
190
+ source = json.loads(args.source or "{}")
191
+ except ValueError as exc:
192
+ raise CliptudeApiError("--source must be a JSON object.") from exc
193
+ if not isinstance(source, dict):
194
+ raise CliptudeApiError("--source must be a JSON object.")
195
+ created = client.create_pick(args.kind, source)
196
+ pick_id, url = str(created.get("pick_id") or ""), str(created.get("url") or "")
197
+ if not pick_id:
198
+ raise CliptudeApiError("Give a pick_id (with --url to open it), or --kind to make a new picker.")
199
+ if url:
200
+ if not url.startswith(("https://", "http://127.0.0.1", "http://localhost")):
201
+ raise CliptudeApiError("--url must be the https link Cliptude gave (browser_picker_url).")
202
+ print(f"Pick in your browser: {url}", file=sys.stderr)
203
+ if not args.no_open:
204
+ webbrowser.open(url)
205
+ deadline = time.monotonic() + max(5.0, float(args.timeout))
206
+ while True:
207
+ payload = client.get_pick(pick_id)
208
+ status = str(payload.get("status") or "")
209
+ if status != "open" or time.monotonic() > deadline:
210
+ return payload
211
+ print("Waiting for your pick in the browser...", file=sys.stderr)
212
+ time.sleep(max(1.0, float(args.interval)))
213
+
214
+
161
215
  def _run_auth(auth_cmd: str) -> None:
162
216
  from cliptude_mcp.auth_login import AuthLoginError, login
163
217
  from cliptude_mcp.credentials import clear_credentials, stored_access_token
@@ -174,6 +228,16 @@ def _run_auth(auth_cmd: str) -> None:
174
228
  clear_credentials()
175
229
  print("Logged out.")
176
230
  return
231
+ from cliptude_mcp.client import resolve_connection
232
+
233
+ conn = resolve_connection()
234
+ if conn["runtime"] == "desktop":
235
+ if conn["error"]:
236
+ print(conn["error"], file=sys.stderr)
237
+ raise SystemExit(1)
238
+ account = CliptudeClient(client_kind="cli").get_account()
239
+ print(f"Using the Cliptude desktop app as {account.get('email')} (no cliptude.com login needed).")
240
+ return
177
241
  if not stored_access_token():
178
242
  print("Not authenticated. Run: cliptude auth login", file=sys.stderr)
179
243
  raise SystemExit(1)
@@ -185,6 +249,19 @@ def _run_auth(auth_cmd: str) -> None:
185
249
  print(f"Logged in{f' as {email}' if email else '.'}")
186
250
 
187
251
 
252
+ def _run_use(target: str | None) -> None:
253
+ from cliptude_mcp.client import chosen_target, resolve_connection, save_target
254
+
255
+ if target:
256
+ save_target(target)
257
+ conn = resolve_connection()
258
+ where = {"desktop": "the Cliptude desktop app", "cloud": "cliptude.com"}.get(conn["runtime"], conn["base_url"])
259
+ print(f"Target: {chosen_target()} → {where}" + (f" ({conn['base_url']})" if conn["base_url"] else ""))
260
+ if conn["error"]:
261
+ print(conn["error"], file=sys.stderr)
262
+ raise SystemExit(1)
263
+
264
+
188
265
  def _review_arg(value: str) -> dict:
189
266
  """--review "quote|author|rating" -> {quote, author, rating}."""
190
267
  parts = [p.strip() for p in value.split("|")]
@@ -214,6 +291,32 @@ def main(argv: list[str] | None = None) -> None:
214
291
  auth_sub.add_parser("logout", help="Delete the local session")
215
292
  auth_sub.add_parser("status", help="Show whether this machine is signed in")
216
293
 
294
+ use = sub.add_parser(
295
+ "use",
296
+ help="Make videos in the Cliptude desktop app or on cliptude.com (no argument: show where)",
297
+ )
298
+ use.add_argument("target", nargs="?", choices=["desktop", "cloud", "auto"],
299
+ help="auto = the desktop app while it is running, else cliptude.com")
300
+
301
+ pk = sub.add_parser(
302
+ "pick",
303
+ help="Open a browser picker (avatars, voices, music, a review to confirm, ...) and wait for the pick",
304
+ description=(
305
+ "Clients without MCP Apps widgets get browser_picker_url and pick_id from the MCP tools. This opens the "
306
+ "link in your browser and waits until you pick (or confirm) there, then prints the result. With --kind "
307
+ "it makes a new picker first."
308
+ ),
309
+ )
310
+ pk.add_argument("pick_id", nargs="?", default="", help="pick_id from the tool result")
311
+ pk.add_argument("--url", default="", help="browser_picker_url from the tool result")
312
+ pk.add_argument("--kind", default="", choices=["", "avatars", "voices", "characters", "choices", "templates",
313
+ "template", "job", "script", "publish_kit", "video"],
314
+ help="Make a new picker of this kind instead")
315
+ pk.add_argument("--source", default="{}", help='Where Cliptude reads it from, JSON, e.g. {"provider": "elevenlabs"}')
316
+ pk.add_argument("--no-open", action="store_true", help="Print the link instead of opening a browser")
317
+ pk.add_argument("--timeout", type=float, default=900.0, help="Seconds to wait (the link lasts 15 minutes)")
318
+ pk.add_argument("--interval", type=float, default=3.0, help="Seconds between checks")
319
+
217
320
  t = sub.add_parser("templates", help="List saved templates")
218
321
  t.add_argument("--limit", type=int, default=20)
219
322
  t.add_argument("--offset", type=int, default=0)
@@ -378,6 +481,12 @@ def main(argv: list[str] | None = None) -> None:
378
481
  default=None,
379
482
  help="No scene transitions; hard cuts only. Omit to use the template.",
380
483
  )
484
+ g.add_argument(
485
+ "--disable-sound-effects",
486
+ action=argparse.BooleanOptionalAction,
487
+ default=None,
488
+ 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.",
489
+ )
381
490
  g.add_argument(
382
491
  "--exclude-animation-type",
383
492
  action="append",
@@ -445,6 +554,8 @@ def main(argv: list[str] | None = None) -> None:
445
554
  ),
446
555
  )
447
556
  cont.add_argument("job_id")
557
+ _add_thumbnail_args(cont, scope="this video")
558
+ _add_review_args(cont)
448
559
 
449
560
  prod = sub.add_parser(
450
561
  "product",
@@ -472,9 +583,16 @@ def main(argv: list[str] | None = None) -> None:
472
583
  ps.add_argument("--cta-url", default="")
473
584
  ps.add_argument("--review", action="append", default=[],
474
585
  help='A real customer review, "quote|author|rating" (repeat up to 3 times)')
586
+ ps.add_argument("--script-file", default="",
587
+ help="Narration you wrote (text file); the job is script_ready at once. Omit to let Cliptude write it")
588
+ ps.add_argument("--plan", action="store_true",
589
+ help="You plan every visual: the job is voiced and stops at plan_ready (plan-check, plan-lock, then product render)")
590
+ _add_review_args(ps)
475
591
  pr = prod_sub.add_parser("render", help="Produce the video from a ready product script")
476
592
  pr.add_argument("job_id")
477
593
  pr.add_argument("--aspect-ratio", default="16:9")
594
+ _add_thumbnail_args(pr, scope="this video")
595
+ _add_review_args(pr)
478
596
  pst = prod_sub.add_parser("status", help="Stage, script, preview link and MP4 of a product video")
479
597
  pst.add_argument("job_id")
480
598
 
@@ -532,6 +650,8 @@ def main(argv: list[str] | None = None) -> None:
532
650
  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
651
  um.add_argument("job_id")
534
652
  um.add_argument("path", help="Local JPG/PNG/WEBP/GIF (up to 15 MB) or MP4/MOV/WEBM/M4V (up to 300 MB)")
653
+ um.add_argument("--split-shots", action="store_true",
654
+ help="Also cut a long source into 3-12 s clips on its cuts, each checked and kept (prints their keep ids)")
535
655
 
536
656
  ed = sub.add_parser("editor", help="Open the timeline editor project for a completed job (prints the timeline)")
537
657
  ed.add_argument("job_id")
@@ -553,6 +673,7 @@ def main(argv: list[str] | None = None) -> None:
553
673
  ag.add_argument("--tier", default="fast", help="fast or smart (see cliptude agent-tiers)")
554
674
  ag.add_argument("--chat", default="", help="Continue an existing agent chat id")
555
675
  ag.add_argument("--wait", action="store_true", help="Poll until the run finishes")
676
+ _add_review_args(ag)
556
677
 
557
678
  ags = sub.add_parser("agent-status", help="Get a Cliptude Agent run")
558
679
  ags.add_argument("project_id")
@@ -569,6 +690,7 @@ def main(argv: list[str] | None = None) -> None:
569
690
  rn.add_argument("--wait", action="store_true", help="Poll until the render finishes")
570
691
  rn.add_argument("--accept-quality-findings", action="store_true",
571
692
  help="Agent-planned jobs: render although plan-review still lists plan quality findings")
693
+ _add_review_args(rn)
572
694
 
573
695
  rs = sub.add_parser("render-status", help="Get an editor render (output_url when done)")
574
696
  rs.add_argument("render_id")
@@ -591,9 +713,17 @@ def main(argv: list[str] | None = None) -> None:
591
713
  if args.cmd == "auth":
592
714
  _run_auth(args.auth_cmd)
593
715
  return
716
+ if args.cmd == "use":
717
+ _run_use(args.target)
718
+ return
594
719
  client = CliptudeClient(client_kind="cli")
595
720
  try:
596
- if args.cmd == "templates":
721
+ if args.cmd == "pick":
722
+ payload = _run_pick(client, args)
723
+ _print(payload)
724
+ if payload.get("status") != "done":
725
+ raise SystemExit(1)
726
+ elif args.cmd == "templates":
597
727
  _print(client.list_templates(limit=args.limit, offset=args.offset))
598
728
  elif args.cmd == "template-create":
599
729
  settings = {}
@@ -685,6 +815,7 @@ def main(argv: list[str] | None = None) -> None:
685
815
  disable_overlays=args.disable_overlays,
686
816
  disable_effects=args.disable_effects,
687
817
  disable_transitions=args.disable_transitions,
818
+ disable_sound_effects=args.disable_sound_effects,
688
819
  excluded_animation_types=args.excluded_animation_types,
689
820
  excluded_transition_kinds=args.excluded_transition_kinds,
690
821
  thumbnail=_thumbnail_from_args(args),
@@ -762,25 +893,34 @@ def main(argv: list[str] | None = None) -> None:
762
893
  elif args.cmd == "plan-report":
763
894
  _print(client.get_plan_report(args.job_id))
764
895
  elif args.cmd == "upload-media":
765
- _print(client.upload_plan_media(args.job_id, args.path))
896
+ _print(client.upload_plan_media(args.job_id, args.path, split_shots=args.split_shots))
766
897
  elif args.cmd == "download-voiceover":
767
898
  dest = Path(args.out)
768
899
  client.download_voiceover_file(args.job_id, dest)
769
900
  _print({"ok": True, "path": str(dest.resolve())})
770
901
  elif args.cmd == "continue":
771
- _print(client.continue_job(args.job_id))
902
+ thumbnail = _thumbnail_from_args(args)
903
+ _print(_spend_reviewed(
904
+ args, lambda token: client.continue_job(args.job_id, thumbnail=thumbnail, review_token=token),
905
+ "Build this video?",
906
+ ))
772
907
  elif args.cmd == "product":
773
908
  if args.product_cmd == "fetch":
774
909
  _print(client.fetch_product_context(args.url_or_query, store_domain=args.store or None))
775
910
  elif args.product_cmd == "script":
776
911
  angle = int(args.angle) if str(args.angle).isdigit() else args.angle
777
- _print(client.draft_product_script(
912
+ script = Path(args.script_file).read_text(encoding="utf-8") if args.script_file else None
913
+ _print(_reviewed(args, lambda token, acks: client.draft_product_script(
778
914
  args.product_id, angle=angle, duration=args.duration, template_id=args.template or None,
779
915
  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
- ))
916
+ reviews=[_review_arg(r) for r in args.review] or None, script=script, plan=args.plan,
917
+ review_token=token, acknowledge=acks,
918
+ ), question="Start this product video?"))
782
919
  elif args.product_cmd == "render":
783
- _print(client.render_product_video(args.job_id, aspect_ratio=args.aspect_ratio))
920
+ thumbnail = _thumbnail_from_args(args)
921
+ _print(_spend_reviewed(args, lambda token: client.render_product_video(
922
+ args.job_id, aspect_ratio=args.aspect_ratio, thumbnail=thumbnail, review_token=token,
923
+ ), "Build this product video?"))
784
924
  else:
785
925
  _print(client.get_product_video_status(args.job_id))
786
926
  elif args.cmd == "editor":
@@ -792,9 +932,10 @@ def main(argv: list[str] | None = None) -> None:
792
932
  if not (prompt or "").strip():
793
933
  raise CliptudeApiError("Provide --prompt or --prompt-file.")
794
934
  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
- )
935
+ payload = _spend_reviewed(args, lambda token: client.run_agent(
936
+ args.project_id, prompt=prompt, tier=args.tier, referenced_item_ids=items, chat_id=args.chat or None,
937
+ review_token=token,
938
+ ), "Run the agent?")
798
939
  if args.wait:
799
940
  run_id = (payload.get("run") or {}).get("id")
800
941
  payload = _wait(lambda: client.get_agent_run(args.project_id, run_id), lambda p: (p.get("run") or {}).get("status"))
@@ -806,7 +947,9 @@ def main(argv: list[str] | None = None) -> None:
806
947
  elif args.cmd == "agent-tiers":
807
948
  _print(client.agent_tiers())
808
949
  elif args.cmd == "render":
809
- payload = client.render_project(args.project_id, accept_quality_findings=args.accept_quality_findings)
950
+ payload = _spend_reviewed(args, lambda token: client.render_project(
951
+ args.project_id, accept_quality_findings=args.accept_quality_findings, review_token=token,
952
+ ), "Render this MP4?")
810
953
  if args.wait:
811
954
  render_id = (payload.get("render") or {}).get("id")
812
955
  payload = _wait(lambda: client.get_render(render_id), lambda p: (p.get("render") or {}).get("status"))