@clipit-ai/cli 0.2.4 → 0.2.7

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,6 +57,7 @@ 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
@@ -60,7 +71,11 @@ Video and clip helpers:
 clipit videos list --json
 clipit videos get <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 --confirm --json
@@ -137,9 +152,9 @@ 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.
 
-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.
+`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.
 
@@ -224,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.
@@ -250,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. |
+| 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`. |