@clipit-ai/cli 0.2.3 → 0.2.6

package/README.md

@@ -38,6 +38,16 @@ For CI or manually created API keys:
 printf '%s' "$CLIPPER_API_KEY" | clipit auth set-key --stdin
 ```
 
+Team operators should store each enterprise workspace key in its own named profile, verify the returned `scope.workspaceId`, and activate that profile before working:
+
+```bash
+printf '%s\n' "$WORKSPACE_API_KEY" | clipit auth set-key --profile client-acme --stdin
+clipit auth status --profile client-acme --json
+clipit auth use client-acme
+```
+
+Interactive `--stdin` entry suppresses terminal echo and completes on the first newline. Keys are never accepted as command-line arguments.
+
 ## Core Commands
 
 ```bash
@@ -47,10 +57,12 @@ clipit doctor --json
 clipit auth status --json
 clipit auth open-settings
 clipit auth profiles --json
+clipit auth use <profile>
 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 +70,28 @@ 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 abort-upload <upload-intent-id> --confirm --json
+clipit videos import-url "https://example.com/video" --confirm --json
+
+# Reuse this key only when retrying after an unknown network outcome
+clipit videos import-url "https://example.com/video" --idempotency-key import-episode-42 --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 +108,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
@@ -134,7 +152,11 @@ If the estimate is greater than the limit, the CLI exits with code `12` and prin
 
 When the server returns HTTP 402, the CLI exits with code `13`. For spend-limit errors, raise the API key spend limit in ClipIt Settings or use a different key; otherwise top up credits at https://clipit.dev/settings (Billing).
 
-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.
+Large `videos upload` and `assets upload` commands print upload progress to stderr when stderr is a TTY and `--json` is not set.
+
+`videos upload` reserves quota and credits through the API, then streams the file directly to signed object-storage URLs. Files at or above 10 MiB use bounded multipart batches, and rerunning the same unchanged file resumes provider-confirmed missing parts with the same deterministic idempotency key. Supply `--idempotency-key` when the same file must retain its identity across a rename or move. The CLI rejects resume attempts when the path, size, timestamps, filename, MIME type, title, profile, or API host changed, and it rechecks the file before sealing the upload. Concurrent resume records are stored atomically as separate user-only files; they contain no signed URLs and expire after the server's 24-hour resume window. Use `videos abort-upload <intent-id> --confirm` to cancel an unfinished transfer and release its storage and credit reservations. The deprecated proxied `POST /api/v1/videos` compatibility endpoint is not used by the CLI.
+
+`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
 
@@ -168,12 +190,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
@@ -210,13 +239,16 @@ The default profile is `default`.
 ```bash
 clipit login --profile work
 clipit auth status --profile work --json
+clipit auth use work
 CLIPIT_PROFILE=work clipit clips list --json
 ```
 
+An explicitly selected profile (`--profile` or `CLIPIT_PROFILE`) and an active non-default profile are authoritative for both credential and base URL. They never silently fall back to a global personal key. With the default profile and no explicit profile selection, the existing environment-variable fallback remains available.
+
 Supported environment variables:
 
-- `CLIPPER_API_KEY`: overrides stored credentials.
-- `CLIPPER_BASE_URL`: overrides the API base URL.
+- `CLIPPER_API_KEY`: supplies the default-profile/CI credential when no named profile is selected.
+- `CLIPPER_BASE_URL`: supplies the default-profile/CI API base URL when no named profile is selected.
 - `CLIPIT_PROFILE`: selects a config profile.
 - `CLIPIT_CONFIG_DIR`: overrides the config directory.
 - `CLIPIT_ALLOW_CUSTOM_HOST=true`: allows non-ClipIt hosts.
@@ -236,10 +268,10 @@ 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. |
+| Auth and setup | `login`, `setup`, `logout`, `doctor`, `auth status`, `auth set-key`, `auth open-settings`, `auth profiles`, `auth use` | Browser-link login, manual key fallback, and fail-closed named workspace profiles. |
+| 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. |
+| Videos and clips | `videos list/get/upload/abort-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`. |
 | Analytics | `analytics overview`, `analytics top-clips`, `analytics post` | `overview` returns aggregate and by-platform metrics. |
 | Exports | `exports start/list/get/wait/download/cancel` | Export jobs poll through `/api/v1/exports/:jobId`; paid start requires `--confirm`. |