@koda-sl/baker-cli 0.203.0 → 0.208.1

package/README.md

@@ -86,8 +86,20 @@ All commands return a JSON envelope:
 
 // Dry-run
 { "ok": true, "dryRun": true, "operation": "images.delete", "params": { "id": "abc123" } }
+
+// Unknown option — the command stops instead of running without it
+{ "ok": false, "error": { "code": "UNKNOWN_ARGUMENT", "message": "--dimension-filter is not an option of `baker ga4 query`.", "fix": { "action": "check_schema", "explanation": "Did you mean --dimensions? Run `baker schema ga4 query` ..." }, "retryable": false } }
 ```
 
+### Unknown options are refused
+
+An option a command does not declare stops the run with `UNKNOWN_ARGUMENT`, naming the
+closest real one. Previously such an option was accepted and ignored, so a call that
+looked like it had filtered or narrowed a result was in fact answering the unfiltered
+question — and nothing in the output said so. Both spellings of an option work
+(`--run-id` and `--runId`), as they always did. Run `baker schema <command>` to see
+every option a command takes.
+
 Use `--output` to change format:
 
 | Format  | Description                        | Best for           | Available on |
@@ -2442,15 +2454,16 @@ Get a single video by ID. `--full` includes the auto-generated **transcript** (B
 baker videos get j571abc123 --full --output md
 ```
 
-### `baker videos upload <file>`
+### `baker videos upload <file|url>`
 
-Upload a video file via Mux direct upload.
+Upload a video. A local path is uploaded directly; an `http(s)` URL is routed to `baker videos ingest`.
 
 ```bash
 baker videos upload ./demo.mp4
 baker videos upload ./demo.mp4 --dry-run
 baker videos upload ./testimonial-maria.mp4 \
   --context "Testimonial from Maria, a real customer, filmed on her phone for the autumn campaign"
+baker videos upload https://www.youtube.com/watch?v=abc123
 ```
 
 Supported extensions: `.mp4`, `.mov`, `.webm`, `.avi`, `.mkv`
@@ -2468,6 +2481,55 @@ baker videos group --group-key "instagram:Cx7Ab9"
 
 Same lookup as `baker images group` and takes either kind of id; the two exist so the noun you happen to hold does not decide whether you can ask.
 
+### `baker videos ingest <url>`
+
+Add a video to the library from a link — a direct video file, or a page on YouTube, TikTok, Vimeo, or Instagram.
+
+```bash
+baker videos ingest https://cdn.example.com/hero-loop.mp4          # → { videoId, via: "direct" }
+baker videos ingest https://www.youtube.com/watch?v=abc123         # → { videoId, via: "download" }
+baker videos ingest https://vimeo.com/12345 --external-id vim:12345
+```
+
+Two routes, chosen from the URL and reported as `via`:
+
+- **direct** — the URL ends in a video extension, so Baker fetches the file itself. Nothing is downloaded locally and there is no size limit.
+- **download** — anything else. The video is downloaded locally, stored, and then ingested. Videos longer than **3 hours** are refused up front, from the link's metadata, before anything is fetched. The downloaded file itself is capped at 16 GB.
+
+A direct URL that Baker cannot fetch retries automatically on the download route and reports `fallbackFrom`. Force the download route with `--download`.
+
+Re-ingesting the same link returns the existing row with `deduped: true` instead of transcoding it twice. On the download route the key is the provider's own id, so the same clip pasted as a share link, a shorts link or a watch link folds into one row; on the direct route it is the URL itself. Pass `--external-id` to supply your own key.
+
+| Flag | Purpose |
+|---|---|
+| `--source` | Provenance. Inferred from the link's host when omitted, and that inference covers 20 video platforms — `youtube`, `instagram`, `tiktok`, `twitter`, `facebook`, `reddit`, `vimeo`, `dailymotion`, `twitch`, `bluesky`, `bilibili`, `vk`, `ok`, `pinterest`, `tumblr`, `snapchat`, `loom`, `streamable`, `newgrounds`, `rutube` — plus `uploaded` and `url`. A link from anywhere else still ingests, recorded as `url`. |
+| `--external-id` | Dedupe key — re-running the same link returns the existing video. Derived from the link automatically on the download route. |
+| `--external-url` | Canonical page URL. Defaults to the input for a page URL. |
+| `--download` | Skip the direct attempt and always download. |
+| `--country` | Two-letter country to fetch from (`US`, `DE`, `JP`). Use when a video is blocked in the region Baker fetches from. |
+| `--context` | What you know that the video cannot show — campaign, who is on camera, intended use. Feeds the analysis, exactly as on `upload`. |
+| `--dry-run` | Preview the resolved route and parameters. |
+
+Baker fetches directly first and only pays for a proxied connection when the site refuses it. `--country` pins those paid connections to a specific place — it does not change the first, free attempt. The result names both the exit used (`egress`) and the country, so a geo-targeted fetch is never invisible after the fact. A region failure says so and suggests the flag; other failures don't, because a different country would not fix them.
+
+### Vimeo needs a signed-in session
+
+Vimeo has removed every anonymous download path — measured against all four of yt-dlp's clients, and the failure is identical through direct, datacenter and residential exits, so it is neither an IP nor a fingerprint problem. Set `VIMEO_COOKIE` on the Convex deployment to the value of the `vimeo` cookie from a logged-in browser session (`npx convex env set VIMEO_COOKIE '<value>'`). That one cookie is sufficient; the rest of the jar is not needed.
+
+Use an account created for this and holding nothing else — the value travels in sandbox-wide environment that the agent can read. Unset, Vimeo simply fails with a message telling the user to upload the file instead. The session expires, and when it does the failure says so explicitly rather than surfacing Vimeo's opaque 401.
+
+An audio-only link (a music or podcast page) is refused up front — there is no picture to store in a video library. A download is also given a time budget scaled to the video's length, capped at 15 minutes, because the turn is blocked while it runs; a video that outruns it says so and points at `upload`.
+
+The download route caps the pull at 1080p — Baker re-encodes for streaming anyway, so fetching a 4K master (what modern YouTube serves by default) only makes the download slower for pixels that get discarded.
+
+**Blocked downloads climb the egress ladder automatically.** The download route goes through the same **direct → datacenter → residential** ladder as every other outbound read (`@baker/proxy`; see [Operations](../../docs/operations.md) → Egress Proxy). There is no proxy flag on any command and nothing to opt into — the unproxied attempt always runs first, so a paid exit costs nothing until a host actually refuses us, and with no `OXYLABS_*` credentials in the environment this is a single plain download.
+
+A rung only opens on evidence that *who we are* was the problem — a 403/429/451, a WAF connection reset, or a bot wall like YouTube's "Sign in to confirm you're not a bot". A private video, a deleted one, a 404 or an unsupported URL fails identically from every address on earth, so it stops after one attempt instead of burning a timeout per tier. That decision is `shouldEscalate`'s, shared with the capture engine and the ad-media downloaders; yt-dlp's stderr is only *parsed* into the signal it takes (`src/lib/ytDlpSignal.ts`), never allowed to judge for itself.
+
+Requires `yt-dlp` on `PATH` (present in the Baker Runtime). Private, age-restricted, or region-locked videos cannot be downloaded — the error carries a `fix` pointing at `baker videos upload <file>`.
+
+**yt-dlp goes stale, and that looks like a broken video.** Large platforms change their players every few weeks and an out-of-date `yt-dlp` then resolves *no* formats at all, failing with "Requested format is not available" or "Only images are available" rather than anything that names the real cause. The error classifies this case separately and says the link is probably fine. The Runtime image installs `yt-dlp` unpinned at build time (`packages/e2b-template/src/template.ts`), so it ages with the image — if platform ingests start failing across the board, rebuild the template before investigating anything else. Direct file URLs don't depend on `yt-dlp` at all and keep working regardless.
+
 ### `baker videos delete <id>`
 
 Delete a video by ID.

package/dist/{chunk-UZYVSPCA.js → chunk-3E33AGNR.js}

@@ -1,6 +1,6 @@
 import {
   debugLogSetting
-} from "./chunk-6NZG2TCM.js";
+} from "./chunk-IRNM3T6B.js";
 
 // src/debugLog.ts
 import { appendFileSync, mkdirSync, renameSync, statSync } from "fs";
@@ -150,4 +150,4 @@ export {
   readBodyForLog,
   installStreamTaps
 };
-//# sourceMappingURL=chunk-UZYVSPCA.js.map
+//# sourceMappingURL=chunk-3E33AGNR.js.map

package/dist/{chunk-SVHFT7AN.js → chunk-3WODSPNZ.js}

@@ -2,13 +2,13 @@ import {
   handleConnectionError,
   needsConnectionFix,
   writeAdsJson
-} from "./chunk-KHHD26LZ.js";
+} from "./chunk-FUSTYLP5.js";
 import {
   ApiError
-} from "./chunk-2R2DEPG7.js";
+} from "./chunk-CRXSLYEX.js";
 import {
   getEnv
-} from "./chunk-6NZG2TCM.js";
+} from "./chunk-IRNM3T6B.js";
 
 // src/commands/ads/meta/shared.ts
 var DAY_MS = 864e5;
@@ -108,4 +108,4 @@ export {
   csvOrJson,
   resolveEffectiveStatus
 };
-//# sourceMappingURL=chunk-SVHFT7AN.js.map
+//# sourceMappingURL=chunk-3WODSPNZ.js.map

package/dist/{chunk-2R2DEPG7.js → chunk-CRXSLYEX.js}

@@ -1,10 +1,10 @@
 import {
   debugLogHttp,
   readBodyForLog
-} from "./chunk-UZYVSPCA.js";
+} from "./chunk-3E33AGNR.js";
 import {
   getEnv
-} from "./chunk-6NZG2TCM.js";
+} from "./chunk-IRNM3T6B.js";
 
 // src/client.ts
 var MAX_RATE_LIMIT_RETRIES = 3;
@@ -198,4 +198,4 @@ export {
   apiGet,
   apiPost
 };
-//# sourceMappingURL=chunk-2R2DEPG7.js.map
+//# sourceMappingURL=chunk-CRXSLYEX.js.map