@clipit-ai/cli 0.2.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Video Clipper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,249 @@
+# ClipIt CLI
+
+Command-line access for ClipIt and shell-capable agents.
+
+The CLI works with any agent framework, including Claude Code, Codex, Hermes, and others. It lets users connect a terminal or agent to ClipIt with a one-time browser approval link, discover Clippy tools, run approved actions, navigate videos and clips, and install local agent skill instructions without storing API keys in those skill files.
+
+## Install
+
+```bash
+npx @clipit-ai/cli --help
+npm install -g @clipit-ai/cli
+```
+
+Node.js 18 or newer is required.
+
+## Login
+
+```bash
+clipit login
+```
+
+The CLI opens ClipIt in your browser and prints a one-time code. Approve the request in the web app, then the CLI stores a scoped credential in:
+
+- macOS/Linux/WSL: `~/.config/clipit/config.json`
+- Windows: `%APPDATA%\ClipIt\config.json`
+
+Generated agent skills never contain the credential. They call the `clipit` command already installed on the user's machine.
+
+For terminals without a browser:
+
+```bash
+clipit login --no-browser
+```
+
+For CI or manually created API keys:
+
+```bash
+printf '%s' "$CLIPPER_API_KEY" | clipit auth set-key --stdin
+```
+
+## Core Commands
+
+```bash
+clipit setup [--agent codex|claude|hermes|openclaw|<any-framework>]
+clipit logout
+clipit doctor --json
+clipit auth status --json
+clipit auth open-settings
+clipit auth profiles --json
+clipit skills list --json
+clipit tools list --json
+clipit tools describe <functionName> --json
+clipit run <functionName> --params @params.json --max-credits 25 --json
+```
+
+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 transcript <videoId> --json
+clipit videos suggest-clips <videoId> --count 5 --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 update <clipId> --title "Better title" --json
+clipit clips render <clipId> --aspect 9:16 --quality high --json
+clipit clips download <clipId> --json
+clipit jobs wait <jobId> --stream
+```
+
+Platform helpers:
+
+```bash
+clipit credits balance --json
+clipit credits usage --json
+clipit credits estimate --operation-type transcription --provider deepgram --metrics @metrics.json --json
+
+clipit analytics overview --days 30 --json
+clipit analytics top-clips --limit 10 --json
+clipit analytics post <socialPostId> --json
+
+clipit exports start --clip-id <clipId> --params @export.json --confirm --json
+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 assets list --json
+clipit assets upload ./brand-logo.png --kind image --json
+clipit assets delete <assetId> --confirm --json
+
+clipit thumbnails generate --clip-id <clipId> --prompt "High contrast thumbnail" --confirm --json
+clipit thumbnails get <thumbnailId> --json
+clipit thumbnails list --clip-id <clipId> --json
+
+clipit broll plan <clipId> --count 3 --confirm --json
+clipit broll generate <clipId> --concept-index 0 --confirm --json
+clipit broll list --clip-id <clipId> --json
+clipit broll get <brollId> --json
+
+clipit social accounts --json
+clipit social post --clip-id <clipId> --platforms x,tiktok --caption "New clip" --confirm --json
+clipit social schedule --clip-id <clipId> --platforms youtube --title "Launch clip" --caption "New clip" --at 2026-07-01T15:00:00.000Z --confirm --json
+clipit social posts --status scheduled --json
+clipit social get <postId> --json
+clipit social cancel <postId> --confirm --json
+```
+
+## Reliability And Spend Guards
+
+The CLI retries only idempotent `GET` requests, with at most two retries for network failures, `429`, `502`, `503`, and `504`. `Retry-After` is honored up to 10 seconds. `POST`, `PATCH`, and `DELETE` requests are never retried. Pass `--no-retry` to disable GET retries.
+
+Non-OK API errors include the server `X-Request-Id` when present. In `--json` mode the error payload includes `requestId`, which is safe to share with ClipIt support.
+
+Use `--max-credits <n>` on paid commands to preflight a cost estimate before the command runs:
+
+```bash
+clipit exports start --clip-id <clipId> --confirm --max-credits 10 --json
+clipit thumbnails generate --clip-id <clipId> --prompt "High contrast thumbnail" --confirm --max-credits 20 --json
+clipit broll generate <clipId> --concept-index 0 --confirm --max-credits 150 --json
+clipit social post --clip-id <clipId> --platforms x,tiktok --caption "New clip" --confirm --max-credits 2 --json
+```
+
+For confirmation-gated commands, `--yes` is an alias for `--confirm`.
+
+If the estimate is greater than the limit, the CLI exits with code `12` and prints the estimate. Explicitly mapped commands are `exports start`, `thumbnails generate`, `broll plan`, `broll generate`, `clips render`, `videos import-url`, `social post`, and `social schedule`. Confirmation-gated `clipit run <functionName>` calls do not have a command-specific estimate mapping; with `--max-credits` they print `estimate unavailable` and require `--confirm`.
+
+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.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | OK |
+| 2 | Usage or validation error |
+| 10 | Auth required |
+| 11 | Permission denied |
+| 12 | Confirmation required, `--max-credits` exceeded, or workflow awaiting approval |
+| 13 | Insufficient credits or spend limit |
+| 20 | Network error |
+| 21 | Server error |
+
+## Agentic Workflows
+
+Use `clipit ask` for natural-language Clippy workflows that may run across multiple tools and pause for approval:
+
+```bash
+clipit context use --video-id <videoId>
+clipit ask "Find the strongest clip in this video and prepare a social edit"
+```
+
+If the workflow needs approval, the CLI exits with code 12 and prints the pending tasks, estimated cost, and the exact approval command:
+
+```bash
+clipit workflow approve <jobId> --approval-id <approvalId> --decision approved
+```
+
+Workflow helpers:
+
+```bash
+clipit ask "Create three clip candidates" --video-id <videoId> --quick --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
+```
+
+Navigation:
+
+```bash
+clipit open settings
+clipit open clip <clipId>
+clipit links clip <clipId> --download --json
+```
+
+## Agent Skills
+
+Install credential-free instructions for a shell-capable agent. The CLI fetches server-rendered instructions from `/api/v1/agent/instructions?target=<agent>&format=json` when authenticated. If the fetch fails or the CLI is offline, it installs a generic fallback skill and records the source in `SKILL.meta.json` next to `SKILL.md`.
+
+```bash
+clipit agent install codex
+clipit agent install claude
+clipit agent install hermes
+clipit agent install generic
+```
+
+Inspect or remove generated skills:
+
+```bash
+clipit agent doctor codex --json
+clipit agent list --json
+clipit agent update codex
+clipit agent uninstall codex
+clipit agent print-skill generic
+```
+
+## Profiles And Environment
+
+The default profile is `default`.
+
+```bash
+clipit login --profile work
+clipit auth status --profile work --json
+CLIPIT_PROFILE=work clipit clips list --json
+```
+
+Supported environment variables:
+
+- `CLIPPER_API_KEY`: overrides stored credentials.
+- `CLIPPER_BASE_URL`: overrides the API base URL.
+- `CLIPIT_PROFILE`: selects a config profile.
+- `CLIPIT_CONFIG_DIR`: overrides the config directory.
+- `CLIPIT_ALLOW_CUSTOM_HOST=true`: allows non-ClipIt hosts.
+- `CLIPIT_TRUSTED_HOSTS=staging.example.com`: comma-separated extra trusted hosts.
+
+## Host Safety
+
+By default the CLI only contacts ClipIt-owned hosts and local development hosts. To use staging or a self-hosted environment, pass:
+
+```bash
+clipit login --base-url https://staging.example.com --allow-custom-host
+```
+
+Only use `--allow-custom-host` for hosts you control or trust. It permits the CLI to send API requests and credentials to that host.
+
+## Public V1 Surface
+
+| 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. |
+| 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`. |
+| 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`. |
+| Assets | `assets list/upload/delete` | Upload signs, PUTs the file to object storage, then finalizes the library asset. Delete requires `--confirm`. |
+| Thumbnails and B-Roll | `thumbnails generate/get/list`, `broll plan/generate/list/get` | Paid generation commands require `--confirm`. |
+| Social | `social accounts/post/schedule/posts/get/cancel` | Publish/schedule/cancel require `--confirm`; `x` maps to the server `twitter` platform. |
+| Agent skills | `agent install/update/uninstall/doctor/print-skill/list` | `doctor` reports whether the installed skill came from the server or fallback. |