@clipit-ai/cli 0.2.3 → 0.2.4

package/README.md

@@ -51,6 +51,7 @@ clipit skills list --json
 clipit tools list --json
 clipit tools describe <functionName> --json
 clipit run <functionName> --params @params.json --max-credits 25 --json
+clipit mcp stdio
 ```
 
 Video and clip helpers:
@@ -58,22 +59,24 @@ Video and clip helpers:
 ```bash
 clipit videos list --json
 clipit videos get <videoId> --json
-clipit videos upload ./source.mp4 --json
-clipit videos import-url "https://example.com/video" --json
-clipit videos transcribe <videoId> --json
+clipit videos upload ./source.mp4 --confirm --json
+clipit videos import-url "https://example.com/video" --confirm --json
+clipit videos transcribe <videoId> --confirm --json
 clipit videos transcript <videoId> --json
-clipit videos suggest-clips <videoId> --count 5 --json
+clipit videos suggest-clips <videoId> --count 5 --confirm --json
 clipit videos delete <videoId> --confirm --json
 
 clipit clips list --video-id <videoId> --json
 clipit clips get <clipId> --json
-clipit clips create --video-id <videoId> --start 12 --end 42 --title "Strong hook" --json
+clipit clips create --video-id <videoId> --start 12 --end 42 --title "Strong hook" --confirm --json
 clipit clips update <clipId> --title "Better title" --json
-clipit clips render <clipId> --aspect 9:16 --quality high --json
+clipit clips render <clipId> --aspect 9:16 --quality high --confirm --json
 clipit clips download <clipId> --json
 clipit jobs wait <jobId> --stream
 ```
 
+`clips get`, `clips list`, `clips create`, and clip-creation tool results include a structured `media` payload. Agents should present `media.url` as an inline `video/mp4` attachment when `media.isEmbeddable` is true. If it is false, the clip has no rendered MP4 yet; show `media.statusLabel` and use `media.appUrl`/`appUrl` as the review or render link.
+
 Platform helpers:
 
 ```bash
@@ -90,10 +93,10 @@ clipit exports list --json
 clipit exports get <jobId> --json
 clipit exports wait <jobId> --stream
 clipit exports download <jobId> --open
-clipit exports cancel <jobId> --json
+clipit exports cancel <jobId> --confirm --json
 
 clipit assets list --json
-clipit assets upload ./brand-logo.png --kind image --json
+clipit assets upload ./brand-logo.png --kind image --confirm --json
 clipit assets delete <assetId> --confirm --json
 
 clipit thumbnails generate --clip-id <clipId> --prompt "High contrast thumbnail" --confirm --json
@@ -136,6 +139,10 @@ When the server returns HTTP 402, the CLI exits with code `13`. For spend-limit
 
 Large `videos upload` and `assets upload` commands print upload progress to stderr about every two seconds when stderr is a TTY and `--json` is not set.
 
+Direct `videos upload` is capped at 100 MB by default so the CLI fails before large multipart bodies hit edge request limits. Use `clipit videos import-url` for URL sources, or set `CLIPIT_CLI_DIRECT_UPLOAD_MAX_BYTES` only when your target host supports larger direct uploads.
+
+`clipit run importVideoFromUrl` and `clipit videos import-url` use the same job-backed URL import path. After either command starts a job, wait with `clipit jobs wait <jobId> --json`; failed URL-import jobs include retryability and unsupported-source fields when the server can classify the source. Long URL imports can remain at 40% while the server is actively downloading; use `phase`, `message`, `lastHeartbeatAt`, and `stalled` from `clipit jobs get|wait` rather than treating unchanged numeric progress as failure. When the server returns `minimumWaitSeconds`, `jobs wait` will honor that longer wait before timing out.
+
 ## Exit codes
 
 | Code | Meaning |
@@ -168,12 +175,19 @@ Workflow helpers:
 
 ```bash
 clipit ask "Create three clip candidates" --video-id <videoId> --quick --stream
+clipit ask "Create and render three strong clips" --video-id <videoId> --auto-confirm-costly --stream
 clipit ask "Prepare a review cut" --clip-id <clipId> --conversation-id <sessionId> --no-wait --json
 clipit workflow status <jobId> --json
 clipit workflow wait <jobId> --stream
 clipit workflow approve <jobId> --approval-id <approvalId> --decision cheaper
 ```
 
+## MCP Stdio Bridge
+
+Use `clipit mcp stdio` from MCP-compatible clients that can launch a local command. It speaks standard MCP `Content-Length` framed JSON-RPC over stdio, exposes ClipIt agent tools through the authenticated CLI profile, supports `initialize`, `tools/list`, and `tools/call`, and delegates execution to `/api/v1/agent/execute`.
+
+Paid generation, publishing, deletion, and other metered tools still require an explicit confirmation step. If a tool call may spend credits or mutate user-visible ClipIt state, the MCP bridge returns a `requiresConfirmation` result instead of executing it; retry only after the user approves and include `confirmed: true` in the tool arguments.
+
 Navigation:
 
 ```bash
@@ -237,7 +251,7 @@ Only use `--allow-custom-host` for hosts you control or trust. It permits the CL
 | Area | Commands | Notes |
 | --- | --- | --- |
 | Auth and setup | `login`, `setup`, `logout`, `doctor`, `auth status`, `auth set-key`, `auth open-settings`, `auth profiles` | Browser-link login plus manual key fallback. |
-| Agent tools | `skills list`, `tools list`, `tools describe`, `run`, `ask`, `workflow status/wait/approve` | Direct tool execution and natural-language Clippy workflows. |
+| Agent tools | `skills list`, `tools list`, `tools describe`, `run`, `ask`, `workflow status/wait/approve`, `mcp stdio` | Direct tool execution, natural-language Clippy workflows, and MCP stdio access. |
 | Context and navigation | `context use/show/clear/build`, `open`, `links`, `examples` | Persist active IDs and open ClipIt review surfaces. |
 | Videos and clips | `videos list/get/upload/import-url/transcribe/transcript/suggest-clips/delete`, `clips list/get/create/update/render/download/delete`, `jobs get/wait` | Core media and render job helpers. |
 | Credits | `credits balance`, `credits usage`, `credits estimate` | Estimate accepts `--metrics @file.json`. |