@koda-sl/baker-cli 0.199.0 → 0.200.0-dev.0a9adf6f7

package/README.md

@@ -2442,15 +2442,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 +2469,41 @@ 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. Capped at 2 GB.
+
+A direct URL that Baker cannot fetch retries automatically on the download route and reports `fallbackFrom`. Force the download route with `--download`.
+
+| Flag | Purpose |
+|---|---|
+| `--source` | Provenance: `url` or `youtube`. Inferred from the URL when omitted. |
+| `--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. |
+| `--dry-run` | Preview the resolved route and parameters. |
+
+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.