@officexapp/vidfarm-devcli 0.21.21 → 0.21.22

package/.agents/skills/vidfarm/SKILL.md

@@ -221,6 +221,7 @@ Choose the narrowest path that satisfies the request.
 2. If the user already knows the goal and needs a suitable template, read `references/core-workflows.md` and use the template discovery flow.
 3. If the task is “change this video,” read `references/editor-workflows.md`.
 4. If the task is “find footage” or “use our existing assets,” read `references/assets-and-sourcing.md`.
+4b. If the task is **“download this video/audio off a website”** (a pasted YouTube / TikTok / Instagram / X post URL the user wants the actual file from), Vidfarm does that for you on a **paid plan** — `POST /api/v1/primitives/videos/download` (or `/audio/download`), devcli `vidfarm download-video <url>` / `vidfarm download-audio <url>`. **Free plan → do not call it; walk the user through opening the URL in Chrome and downloading it from the page, then `vidfarm put-file` the local file in for $0.** Details in `references/assets-and-sourcing.md` → `references/primitives.md`.
 5. If the task is scripted, local, CI-driven, or `vidfarm serve`-based, read `references/automation-and-local-dev.md`.
 6. If the task explicitly asks for a primitive or needs specialized generation/transcription work, read `references/primitives.md`.
 7. If the task is the MARKETPLACE (ordering videos from specialist agents): browsing is web-only for paying customers — send the human to https://vidfarm.cc/marketplace, never render it locally. Placing/listing orders is the thin REST wrapper in `references/core-workflows.md` (§ Marketplace); anything deeper on a gig (inbox, proofs, payouts) needs the external Dollar Platoon skill — `npx skills add https://github.com/OfficeXApp/dollarplatoon-skill` — the same way FlockPoster work beyond scheduling needs `npx skills add https://github.com/OfficeXApp/flockposter-skill`.

package/.agents/skills/vidfarm/references/assets-and-sourcing.md

@@ -1,3 +1,20 @@
+## Download a video from a website (Vidfarm fetches it for you — paid plans)
+
+**Yes, Vidfarm can download videos off the web for the user.** When someone pastes a YouTube / TikTok / Instagram / X (Twitter) / other supported post URL and wants the actual file — "grab this video", "save this clip", "get me that audio" — you do **not** need yt-dlp, a browser extension, or an apology. One primitive does it and returns a durable Vidfarm-hosted asset:
+
+| Want | Call | devcli |
+| --- | --- | --- |
+| The video (or a photo/carousel post → ordered slideshow) | `POST /api/v1/primitives/videos/download` `{ tracer, payload: { source_url, quality?: "best"\|"hd"\|"full_hd" } }` | `vidfarm download-video <url>` |
+| Just the audio/music/voice track | `POST /api/v1/primitives/audio/download` `{ tracer, payload: { source_url } }` | `vidfarm download-audio <url>` |
+
+Both are async primitive jobs — poll `GET /api/v1/primitives/jobs/:jobId` until `succeeded`, then read `primary_file_url`. Full field-level detail (slideshow response shape, billing, examples) lives in `references/primitives.md`.
+
+**PAID PLANS ONLY.** These ride a paid third-party resolver billed to the wallet, so a free-plan customer gets `402 insufficient_funds`. Check the plan / cost mode before promising it.
+
+**Free-plan users — the fallback is Chrome, and it works:** tell them (or, if you have browser automation, do it yourself) to **open the URL in Chrome and download the video from there** — right-click → *Save video as*, the downloads pane, DevTools → Network, or a Googled `"<platform> video downloader"` site in that same session. Then bring the local file in for free with `vidfarm put-file ./the-file.mp4 --folder <folder>` or the web uploader. Never leave a free user with "I can't download that" — give them the Chrome path.
+
+**Don't reach for this when the real goal is clips.** If the user wants short clips mined out of a long video, `POST /raws/scan` with `source_url` already downloads the source for you as part of the hunt (below) — a separate download call is wasted spend.
+
 ## Raws (long-form → short-form raws)
 
 Mine a **long-form** video (podcast, stream VOD, webinar, any YouTube/TikTok/IG/X URL, or an upload) into a library of tagged, searchable **raws**. This is the `/raws` surface — browse it at `https://vidfarm.cc/library/raws` (the Library page's "Approved / Raws" tabs).

package/.agents/skills/vidfarm/references/automation-and-local-dev.md

@@ -175,9 +175,11 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm wallet [--job <id>\|--tracer <t>] [--limit <n>]` | `GET /api/v1/user/me/wallet` | cost log: balance + lifetime spend + recent charges. `--job <renderJobId>` prints **what that one video cost** (sums its charges); `--tracer <t>` sums a tracer. Cloud-only, paid plan. Aliases: `spend`, `costs` |
 | `vidfarm provider-keys` / `vidfarm add-provider-key <p> <secret>` | `GET`·`POST /api/v1/user/me/provider-keys` | manage AI keys |
 | `vidfarm upload <file> [--folder <path>]` | presign → S3 PUT → finalize (`.../temporary-files/presign` + `.../temporary-files`) | upload → durable URL (ephemeral, 30-day TTL; prefer `--folder temp` for scratch). Goes direct to S3, so large files (up to **200 MB**) bypass the ~6 MB Lambda body limit |
-| `vidfarm download <url> [dest]` | (streams any URL to disk) | download media |
-| `vidfarm download-post <url> [--quality best\|hd\|full_hd]` | `POST /api/v1/primitives/videos/download` + poll | download a social/media post into a durable MP4 or slideshow |
-| `vidfarm download-post-audio <url>` | `POST /api/v1/primitives/audio/download` + poll | download a social/media post's audio into a durable audio file |
+| `vidfarm download <url> [dest]` | (streams any URL to disk) | download media from a **direct** media URL. Free — no plan, no job |
+| `vidfarm download-video <url> [--quality best\|hd\|full_hd]` | `POST /api/v1/primitives/videos/download` + poll | **download a video FROM A WEBSITE** (YouTube/TikTok/IG/X/other supported posts) into durable Vidfarm media; photo/carousel posts return an ordered slideshow. **PAID PLAN** (wallet-billed resolver; free plans get 402). Aliases: `download-post`, `download-url` |
+| `vidfarm download-audio <url>` | `POST /api/v1/primitives/audio/download` + poll | download just the AUDIO track (music/voice) off a website post into a durable audio file. **PAID PLAN**. Alias: `download-post-audio` |
+
+> **Free plan / `cost-mode minimize`:** both download commands are gated by `guardBilled` and will refuse or warn. The free path is **Chrome**: open the URL in a real browser, save the file off the page (right-click → *Save video as*, downloads pane, or a Googled `"<platform> video downloader"` site), then `vidfarm put-file ./the-file.mp4 --folder <folder>` to bring it in for $0. The CLI prints these steps on a 402. Never tell a free user the video simply can't be downloaded.
 | `vidfarm files [--folder <path>]` | `GET /api/v1/user/me/attachments` | list My Files assets + folders |
 | `vidfarm files --search "…" [--folder <path>]` | `POST /api/v1/user/me/attachments/search` | find My Files assets by MEANING (keyword + vector over name/folder/notes) |
 | `vidfarm get-file <id> [dest] [--print]` | (resolve id → view_url, then stream/print) | read one My Files asset |

package/.agents/skills/vidfarm/references/primitives.md

@@ -51,9 +51,11 @@ curl -X POST "$VIDFARM_BASE/api/v1/primitives/images/create-overlay" \
   -d '{"tracer": "vox-overlay", "payload": {"prompt": "a friendly cartoon lightbulb mascot, flat vector illustration", "aspect_ratio": "1:1"}}'
 ```
 
-## Primitive: videos/download
+## Primitive: videos/download — **Vidfarm downloads videos off websites for you**
 
-Download a supported social/media post URL into a durable Vidfarm-hosted VISUAL asset. This route is intentionally broader than its old name suggests: it returns either a normal MP4 for video posts, or a slideshow payload for photo/carousel posts.
+**Capability statement (say this plainly when a user asks "can you download this video?"): yes — on a paid plan, Vidfarm downloads a video straight off a website URL for you.** Hand it a YouTube / TikTok / Instagram / X (Twitter) / other supported post URL and it returns a durable Vidfarm-hosted file. No local yt-dlp, no browser extension, no "I can't access that URL." The route is intentionally broader than its old name suggests: it returns either a normal MP4 for video posts, or a slideshow payload for photo/carousel posts.
+
+**Paid-only, and that gate is real.** The resolver is a paid RapidAPI pass-through billed to the wallet, so a free-plan customer gets `402 insufficient_funds`. Never promise this to a free user — route them to the browser fallback below instead.
 
 - `POST /api/v1/primitives/videos/download`
 - Body: `{ "tracer": "...", "payload": { "source_url": "https://...", "quality"?: "best" | "hd" | "full_hd", "save_manifest"?: true }, "webhook_url"?: "..." }`
@@ -61,8 +63,20 @@ Download a supported social/media post URL into a durable Vidfarm-hosted VISUAL
   - Video post: read `primary_file_url` / `video.file_url` / `videoUrl` for the durable MP4.
   - Photo/carousel post: read `mediaKind: "slideshow"`, ordered `slideImageUrls[]`, optional `slideAudioUrl`, and `primary_file_url` (first slide image).
 - Billing: RapidAPI pass-through wallet charge (`rapidapi_video_download`) plus the small mirror/extract pass (`video_download_lambda` when MP4 download is involved).
-- Free-plan / no-spend rule: do **not** use this paid route when the user wants a free path. In the web app, tell them to use the browser to find a downloader instead. Fallback wording is explicit: suggest Googling `"youtube video downloader"` or `"tiktok/twitter/instagram/etc audio/video downloader"`.
-- devcli wrapper: `vidfarm download-post <url> [--quality best|hd|full_hd]`
+- devcli wrapper: `vidfarm download-video <url> [--quality best|hd|full_hd]` (aliases: `download-post`, `download-url`)
+
+### FREE-PLAN FALLBACK — drive Chrome instead (never dead-end the user)
+
+If the user is on the free plan, says "don't spend money", or cost mode is `minimize`, do **not** call this route. **Load the URL in Chrome and download it by that means** — it costs $0.00 and needs no Vidfarm plan:
+
+1. Open the post/page in Chrome. A real browser session carries the login/consent/age walls that a bare `fetch` can't.
+2. Save the video off the page — right-click → *Save video as*, the browser's downloads pane, or DevTools → Network → the media response.
+3. If the page won't hand it over, Google `"youtube video downloader"` (or `"tiktok/instagram/x/twitter video downloader"`) and use one of those sites in the same Chrome session.
+4. Bring the resulting local file into Vidfarm for free: `vidfarm put-file ./the-file.mp4 --folder <folder>` (devcli) or the web app's upload. From there it's a normal durable asset.
+
+If you're a desktop coding agent with browser automation (Playwright/Puppeteer/CDP, or the user's own Chrome), you can perform steps 1–3 yourself. If you're the web copilot with no browser tool, hand the user these steps — do not claim you downloaded it.
+
+Say the tradeoff out loud once: *"Downloading it for you is a paid-plan feature; on the free plan I'll walk you through grabbing it in Chrome instead."*
 
 Example:
 
@@ -81,9 +95,9 @@ Download just the original audio/music/voice track from a supported social/media
 - Body: `{ "tracer": "...", "payload": { "source_url": "https://...", "save_manifest"?: true }, "webhook_url"?: "..." }`
 - Response: standard primitive job. Poll `GET /api/v1/primitives/jobs/:jobId` until `status: "succeeded"`, then read `primary_file_url` / `audio.file_url` / `audioUrl`.
 - Behavior: prefers the provider's direct audio track when present; otherwise resolves the source video and extracts audio server-side.
-- Billing: same RapidAPI wallet class as `videos/download`.
-- Free-plan / no-spend rule: same as the visual download route. Use the browser and, if needed, suggest Googling `"youtube audio downloader"` or `"tiktok/twitter/instagram/etc audio/video downloader"` instead of spending wallet credits.
-- devcli wrapper: `vidfarm download-post-audio <url>`
+- Billing: same RapidAPI wallet class as `videos/download` — **paid plans only**; free plans get `402`.
+- Free-plan / no-spend rule: identical to the visual route — **load the URL in Chrome and download from there**, then `vidfarm put-file` the result. Google `"youtube audio downloader"` or `"tiktok/twitter/instagram/etc audio downloader"` if the page won't release the track. See the FREE-PLAN FALLBACK block above.
+- devcli wrapper: `vidfarm download-audio <url>` (alias: `download-post-audio`)
 
 Example:
 

package/SKILL.director.md

@@ -221,6 +221,7 @@ Choose the narrowest path that satisfies the request.
 2. If the user already knows the goal and needs a suitable template, read `references/core-workflows.md` and use the template discovery flow.
 3. If the task is “change this video,” read `references/editor-workflows.md`.
 4. If the task is “find footage” or “use our existing assets,” read `references/assets-and-sourcing.md`.
+4b. If the task is **“download this video/audio off a website”** (a pasted YouTube / TikTok / Instagram / X post URL the user wants the actual file from), Vidfarm does that for you on a **paid plan** — `POST /api/v1/primitives/videos/download` (or `/audio/download`), devcli `vidfarm download-video <url>` / `vidfarm download-audio <url>`. **Free plan → do not call it; walk the user through opening the URL in Chrome and downloading it from the page, then `vidfarm put-file` the local file in for $0.** Details in `references/assets-and-sourcing.md` → `references/primitives.md`.
 5. If the task is scripted, local, CI-driven, or `vidfarm serve`-based, read `references/automation-and-local-dev.md`.
 6. If the task explicitly asks for a primitive or needs specialized generation/transcription work, read `references/primitives.md`.
 7. If the task is the MARKETPLACE (ordering videos from specialist agents): browsing is web-only for paying customers — send the human to https://vidfarm.cc/marketplace, never render it locally. Placing/listing orders is the thin REST wrapper in `references/core-workflows.md` (§ Marketplace); anything deeper on a gig (inbox, proofs, payouts) needs the external Dollar Platoon skill — `npx skills add https://github.com/OfficeXApp/dollarplatoon-skill` — the same way FlockPoster work beyond scheduling needs `npx skills add https://github.com/OfficeXApp/flockposter-skill`.
@@ -1020,6 +1021,23 @@ For anything bespoke, pass raw stops: `vidfarm keyframes ./work --layer robot --
 
 **Pick the store by lifetime.** A throwaway intermediate (cloud render source, a `place` scratch asset) belongs in the 30-day `temp/` store: `vidfarm upload clip.mp4 --folder temp`, `vidfarm place … --folder temp` — quarantined in one place you can periodically purge. Anything you **approve/share is permanent**, so `vidfarm approve --video ./final.mp4` uploads to **durable My Files** by default (the share video would otherwise 404 after the temp store's 30-day deletion). Only add `vidfarm approve --temp` when you deliberately want a disposable 30-day preview.
 
+## Download a video from a website (Vidfarm fetches it for you — paid plans)
+
+**Yes, Vidfarm can download videos off the web for the user.** When someone pastes a YouTube / TikTok / Instagram / X (Twitter) / other supported post URL and wants the actual file — "grab this video", "save this clip", "get me that audio" — you do **not** need yt-dlp, a browser extension, or an apology. One primitive does it and returns a durable Vidfarm-hosted asset:
+
+| Want | Call | devcli |
+| --- | --- | --- |
+| The video (or a photo/carousel post → ordered slideshow) | `POST /api/v1/primitives/videos/download` `{ tracer, payload: { source_url, quality?: "best"\|"hd"\|"full_hd" } }` | `vidfarm download-video <url>` |
+| Just the audio/music/voice track | `POST /api/v1/primitives/audio/download` `{ tracer, payload: { source_url } }` | `vidfarm download-audio <url>` |
+
+Both are async primitive jobs — poll `GET /api/v1/primitives/jobs/:jobId` until `succeeded`, then read `primary_file_url`. Full field-level detail (slideshow response shape, billing, examples) lives in `references/primitives.md`.
+
+**PAID PLANS ONLY.** These ride a paid third-party resolver billed to the wallet, so a free-plan customer gets `402 insufficient_funds`. Check the plan / cost mode before promising it.
+
+**Free-plan users — the fallback is Chrome, and it works:** tell them (or, if you have browser automation, do it yourself) to **open the URL in Chrome and download the video from there** — right-click → *Save video as*, the downloads pane, DevTools → Network, or a Googled `"<platform> video downloader"` site in that same session. Then bring the local file in for free with `vidfarm put-file ./the-file.mp4 --folder <folder>` or the web uploader. Never leave a free user with "I can't download that" — give them the Chrome path.
+
+**Don't reach for this when the real goal is clips.** If the user wants short clips mined out of a long video, `POST /raws/scan` with `source_url` already downloads the source for you as part of the hunt (below) — a separate download call is wasted spend.
+
 ## Raws (long-form → short-form raws)
 
 Mine a **long-form** video (podcast, stream VOD, webinar, any YouTube/TikTok/IG/X URL, or an upload) into a library of tagged, searchable **raws**. This is the `/raws` surface — browse it at `https://vidfarm.cc/library/raws` (the Library page's "Approved / Raws" tabs).
@@ -1321,9 +1339,11 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm wallet [--job <id>\|--tracer <t>] [--limit <n>]` | `GET /api/v1/user/me/wallet` | cost log: balance + lifetime spend + recent charges. `--job <renderJobId>` prints **what that one video cost** (sums its charges); `--tracer <t>` sums a tracer. Cloud-only, paid plan. Aliases: `spend`, `costs` |
 | `vidfarm provider-keys` / `vidfarm add-provider-key <p> <secret>` | `GET`·`POST /api/v1/user/me/provider-keys` | manage AI keys |
 | `vidfarm upload <file> [--folder <path>]` | presign → S3 PUT → finalize (`.../temporary-files/presign` + `.../temporary-files`) | upload → durable URL (ephemeral, 30-day TTL; prefer `--folder temp` for scratch). Goes direct to S3, so large files (up to **200 MB**) bypass the ~6 MB Lambda body limit |
-| `vidfarm download <url> [dest]` | (streams any URL to disk) | download media |
-| `vidfarm download-post <url> [--quality best\|hd\|full_hd]` | `POST /api/v1/primitives/videos/download` + poll | download a social/media post into a durable MP4 or slideshow |
-| `vidfarm download-post-audio <url>` | `POST /api/v1/primitives/audio/download` + poll | download a social/media post's audio into a durable audio file |
+| `vidfarm download <url> [dest]` | (streams any URL to disk) | download media from a **direct** media URL. Free — no plan, no job |
+| `vidfarm download-video <url> [--quality best\|hd\|full_hd]` | `POST /api/v1/primitives/videos/download` + poll | **download a video FROM A WEBSITE** (YouTube/TikTok/IG/X/other supported posts) into durable Vidfarm media; photo/carousel posts return an ordered slideshow. **PAID PLAN** (wallet-billed resolver; free plans get 402). Aliases: `download-post`, `download-url` |
+| `vidfarm download-audio <url>` | `POST /api/v1/primitives/audio/download` + poll | download just the AUDIO track (music/voice) off a website post into a durable audio file. **PAID PLAN**. Alias: `download-post-audio` |
+
+> **Free plan / `cost-mode minimize`:** both download commands are gated by `guardBilled` and will refuse or warn. The free path is **Chrome**: open the URL in a real browser, save the file off the page (right-click → *Save video as*, downloads pane, or a Googled `"<platform> video downloader"` site), then `vidfarm put-file ./the-file.mp4 --folder <folder>` to bring it in for $0. The CLI prints these steps on a 402. Never tell a free user the video simply can't be downloaded.
 | `vidfarm files [--folder <path>]` | `GET /api/v1/user/me/attachments` | list My Files assets + folders |
 | `vidfarm files --search "…" [--folder <path>]` | `POST /api/v1/user/me/attachments/search` | find My Files assets by MEANING (keyword + vector over name/folder/notes) |
 | `vidfarm get-file <id> [dest] [--print]` | (resolve id → view_url, then stream/print) | read one My Files asset |
@@ -1556,9 +1576,11 @@ curl -X POST "$VIDFARM_BASE/api/v1/primitives/images/create-overlay" \
   -d '{"tracer": "vox-overlay", "payload": {"prompt": "a friendly cartoon lightbulb mascot, flat vector illustration", "aspect_ratio": "1:1"}}'
 ```
 
-## Primitive: videos/download
+## Primitive: videos/download — **Vidfarm downloads videos off websites for you**
+
+**Capability statement (say this plainly when a user asks "can you download this video?"): yes — on a paid plan, Vidfarm downloads a video straight off a website URL for you.** Hand it a YouTube / TikTok / Instagram / X (Twitter) / other supported post URL and it returns a durable Vidfarm-hosted file. No local yt-dlp, no browser extension, no "I can't access that URL." The route is intentionally broader than its old name suggests: it returns either a normal MP4 for video posts, or a slideshow payload for photo/carousel posts.
 
-Download a supported social/media post URL into a durable Vidfarm-hosted VISUAL asset. This route is intentionally broader than its old name suggests: it returns either a normal MP4 for video posts, or a slideshow payload for photo/carousel posts.
+**Paid-only, and that gate is real.** The resolver is a paid RapidAPI pass-through billed to the wallet, so a free-plan customer gets `402 insufficient_funds`. Never promise this to a free user — route them to the browser fallback below instead.
 
 - `POST /api/v1/primitives/videos/download`
 - Body: `{ "tracer": "...", "payload": { "source_url": "https://...", "quality"?: "best" | "hd" | "full_hd", "save_manifest"?: true }, "webhook_url"?: "..." }`
@@ -1566,8 +1588,20 @@ Download a supported social/media post URL into a durable Vidfarm-hosted VISUAL
   - Video post: read `primary_file_url` / `video.file_url` / `videoUrl` for the durable MP4.
   - Photo/carousel post: read `mediaKind: "slideshow"`, ordered `slideImageUrls[]`, optional `slideAudioUrl`, and `primary_file_url` (first slide image).
 - Billing: RapidAPI pass-through wallet charge (`rapidapi_video_download`) plus the small mirror/extract pass (`video_download_lambda` when MP4 download is involved).
-- Free-plan / no-spend rule: do **not** use this paid route when the user wants a free path. In the web app, tell them to use the browser to find a downloader instead. Fallback wording is explicit: suggest Googling `"youtube video downloader"` or `"tiktok/twitter/instagram/etc audio/video downloader"`.
-- devcli wrapper: `vidfarm download-post <url> [--quality best|hd|full_hd]`
+- devcli wrapper: `vidfarm download-video <url> [--quality best|hd|full_hd]` (aliases: `download-post`, `download-url`)
+
+### FREE-PLAN FALLBACK — drive Chrome instead (never dead-end the user)
+
+If the user is on the free plan, says "don't spend money", or cost mode is `minimize`, do **not** call this route. **Load the URL in Chrome and download it by that means** — it costs $0.00 and needs no Vidfarm plan:
+
+1. Open the post/page in Chrome. A real browser session carries the login/consent/age walls that a bare `fetch` can't.
+2. Save the video off the page — right-click → *Save video as*, the browser's downloads pane, or DevTools → Network → the media response.
+3. If the page won't hand it over, Google `"youtube video downloader"` (or `"tiktok/instagram/x/twitter video downloader"`) and use one of those sites in the same Chrome session.
+4. Bring the resulting local file into Vidfarm for free: `vidfarm put-file ./the-file.mp4 --folder <folder>` (devcli) or the web app's upload. From there it's a normal durable asset.
+
+If you're a desktop coding agent with browser automation (Playwright/Puppeteer/CDP, or the user's own Chrome), you can perform steps 1–3 yourself. If you're the web copilot with no browser tool, hand the user these steps — do not claim you downloaded it.
+
+Say the tradeoff out loud once: *"Downloading it for you is a paid-plan feature; on the free plan I'll walk you through grabbing it in Chrome instead."*
 
 Example:
 
@@ -1586,9 +1620,9 @@ Download just the original audio/music/voice track from a supported social/media
 - Body: `{ "tracer": "...", "payload": { "source_url": "https://...", "save_manifest"?: true }, "webhook_url"?: "..." }`
 - Response: standard primitive job. Poll `GET /api/v1/primitives/jobs/:jobId` until `status: "succeeded"`, then read `primary_file_url` / `audio.file_url` / `audioUrl`.
 - Behavior: prefers the provider's direct audio track when present; otherwise resolves the source video and extracts audio server-side.
-- Billing: same RapidAPI wallet class as `videos/download`.
-- Free-plan / no-spend rule: same as the visual download route. Use the browser and, if needed, suggest Googling `"youtube audio downloader"` or `"tiktok/twitter/instagram/etc audio/video downloader"` instead of spending wallet credits.
-- devcli wrapper: `vidfarm download-post-audio <url>`
+- Billing: same RapidAPI wallet class as `videos/download` — **paid plans only**; free plans get `402`.
+- Free-plan / no-spend rule: identical to the visual route — **load the URL in Chrome and download from there**, then `vidfarm put-file` the result. Google `"youtube audio downloader"` or `"tiktok/twitter/instagram/etc audio downloader"` if the page won't release the track. See the FREE-PLAN FALLBACK block above.
+- devcli wrapper: `vidfarm download-audio <url>` (alias: `download-post-audio`)
 
 Example:
 

package/SKILL.md

@@ -73,6 +73,7 @@ For composition *authoring* craft (motion, keyframes, scene design), Vidfarm shi
 2. "Find a template and start" → `references/core-workflows.md`
 3. "Change / re-theme this video" → `references/editor-workflows.md`
 4. "Find footage / use our assets" → `references/assets-and-sourcing.md`
+4b. **"Download this video/audio from <a website URL>"** → Vidfarm fetches it for you on a **paid plan**: `POST /api/v1/primitives/videos/download` (or `/audio/download`); devcli `vidfarm download-video <url>` / `vidfarm download-audio <url>`. Works on YouTube, TikTok, Instagram, X, and other supported posts; returns a durable Vidfarm file (photo/carousel posts → an ordered slideshow). **Free plan gets a 402 — don't call it. Tell the user (or, with browser automation, do it yourself) to open the URL in Chrome and download it from the page, then `vidfarm put-file ./the-file.mp4` to bring it in for $0.** Never answer "I can't download that." Details: `references/assets-and-sourcing.md`.
 5. "Script / batch / render loop" → `references/automation-and-local-dev.md`
 6. "I need TTS / music / captions / background removal" → `references/primitives.md`
 

package/dist/src/cli.js

@@ -600,12 +600,19 @@ Files (multi-step flows the devcli handles for you):
     --notes <text>          Metadata notes (what it is / when to use it) — vector-embedded for search
                             e.g. vidfarm put-file About.md --folder acme-skincare
                                  echo "..." | vidfarm put-file --stdin --as About.md --folder acme
-  download <url> [dest]     Stream any Vidfarm/media URL to disk
-  download-post <url>       Download a social/media post into Vidfarm media → POST /api/v1/primitives/videos/download
+  download <url> [dest]     Stream any Vidfarm/media URL to disk (free — direct media URLs only)
+  download-video <url>      PAID. Download a video FROM A WEBSITE (YouTube, TikTok, Instagram,
+    (aka download-post)     X/Twitter, and other supported posts) into durable Vidfarm media.
+                            Photo/carousel posts come back as an ordered slideshow.
+                            → POST /api/v1/primitives/videos/download
     --quality <q>           best | hd | full_hd (default: best)
     --no-wait               Return the queued job immediately instead of polling
-  download-post-audio <url> Download a social/media post's audio into Vidfarm → POST /api/v1/primitives/audio/download
+  download-audio <url>      PAID. Download just the AUDIO track (music/voice) from a website post
+    (aka download-post-audio)  → POST /api/v1/primitives/audio/download
     --no-wait               Return the queued job immediately instead of polling
+                            FREE PLAN: both bill the wallet via a paid resolver. If the user is
+                            free/no-spend, don't call them — open the URL in Chrome and download
+                            it from the page, then 'vidfarm put-file ./the-file' to bring it in.
   tasks                     Cloud Status: imports · forks · renders · jobs → GET /api/v1/user/me/tasks
     --running|--done|--error  Filter (or --status <all|running|done|error>); --limit <n>
   wallet                    Wallet cost log: balance + what each video cost → GET /api/v1/user/me/wallet
@@ -769,7 +776,10 @@ function loadDotEnvCredentials(cwd = process.cwd()) {
 async function main() {
     const argv = process.argv.slice(2);
     loadDotEnvCredentials();
-    if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+    // `help` must be caught here too: without it the bare word falls through the
+    // dispatch switch and is treated as a TEMPLATE ID by the default `serve` case,
+    // which boots a local server on :3000 instead of printing help.
+    if (argv.length === 0 || argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h") {
         process.stdout.write(HELP);
         return;
     }
@@ -952,10 +962,14 @@ async function main() {
         case "download":
             await runDownloadCommand(rest);
             return;
+        // Aliases: agents look for "download a video from a website", not "post".
         case "download-post":
+        case "download-video":
+        case "download-url":
             await runDownloadPostCommand(rest);
             return;
         case "download-post-audio":
+        case "download-audio":
             await runDownloadPostAudioCommand(rest);
             return;
         case "files":
@@ -6877,6 +6891,27 @@ async function runDownloadCommand(argv) {
         console.log(`${GREEN}Downloaded ${formatBytes(bytes)} → ${dest}${RESET}`);
     }
 }
+// The FREE fallback for the paid download primitives. Both routes ride a paid
+// RapidAPI resolver billed to the wallet, so a free-plan customer gets a 402.
+// Rather than dead-ending them, tell the agent to drive the user's own browser:
+// open the URL in Chrome and download it from there (no Vidfarm spend).
+// NOTE: a hoisted function, NOT a module const — `void main()` runs synchronously
+// until its first await, so a const declared this far down the file is still in
+// its TDZ when a command handler reads it (same gotcha as the *_HELP consts).
+function downloadFreeAlternative() {
+    return "open the URL in Chrome and download it from the page yourself ($0.00 — no wallet spend)";
+}
+function printDownloadFreePathHint(ctx, kind) {
+    if (ctx.json)
+        return;
+    const noun = kind === "video" ? "video" : "audio";
+    console.log("");
+    console.log(`${YELLOW}Free path (no Vidfarm spend):${RESET} load the URL in Chrome and grab the ${noun} from there.`);
+    console.log(`${DIM}  1. Open the post/page in Chrome (a real browser session handles the login/consent walls).${RESET}`);
+    console.log(`${DIM}  2. Save the ${noun} from the page — right-click → Save, the browser's downloads, or a downloader site.${RESET}`);
+    console.log(`${DIM}  3. Google "youtube ${noun} downloader" or "tiktok/instagram/x ${noun} downloader" if the page won't give it up.${RESET}`);
+    console.log(`${DIM}  4. Then bring the local file into Vidfarm for free: vidfarm put-file ./the-file --folder <folder>${RESET}`);
+}
 async function runDownloadPostCommand(argv) {
     const parsed = parseArgs({
         args: argv,
@@ -6891,6 +6926,11 @@ async function runDownloadPostCommand(argv) {
         throw new Error("download-post --quality must be one of: best, hd, full_hd.");
     }
     const ctx = commonContext(parsed.values);
+    guardBilled(ctx, {
+        label: "download a video from a website (paid plan — RapidAPI resolver)",
+        estimate: "small per-download wallet charge",
+        freeAlternative: downloadFreeAlternative()
+    });
     const tracer = String(parsed.values.tracer ?? `devcli-download-post-${Date.now().toString(36)}`);
     const submit = await apiRequest({
         method: "POST",
@@ -6899,6 +6939,9 @@ async function runDownloadPostCommand(argv) {
         auth: ctx.auth,
         body: { tracer, payload: { source_url: url, quality } }
     });
+    if (!submit.ok && (submit.status === 402 || submit.status === 401 || submit.status === 403)) {
+        printDownloadFreePathHint(ctx, "video");
+    }
     assertApiOk(submit, "download-post");
     const jobId = submit.json?.job_id;
     if (!jobId || parsed.values["no-wait"]) {
@@ -6920,6 +6963,11 @@ async function runDownloadPostAudioCommand(argv) {
     if (!url)
         throw new Error("download-post-audio requires a source URL.");
     const ctx = commonContext(parsed.values);
+    guardBilled(ctx, {
+        label: "download audio from a website (paid plan — RapidAPI resolver)",
+        estimate: "small per-download wallet charge",
+        freeAlternative: downloadFreeAlternative()
+    });
     const tracer = String(parsed.values.tracer ?? `devcli-download-post-audio-${Date.now().toString(36)}`);
     const submit = await apiRequest({
         method: "POST",
@@ -6928,6 +6976,9 @@ async function runDownloadPostAudioCommand(argv) {
         auth: ctx.auth,
         body: { tracer, payload: { source_url: url } }
     });
+    if (!submit.ok && (submit.status === 402 || submit.status === 401 || submit.status === 403)) {
+        printDownloadFreePathHint(ctx, "audio");
+    }
     assertApiOk(submit, "download-post-audio");
     const jobId = submit.json?.job_id;
     if (!jobId || parsed.values["no-wait"]) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@officexapp/vidfarm-devcli",
-  "version": "0.21.21",
+  "version": "0.21.22",
   "description": "Local bridge for the Vidfarm Trackpad Editor. `vidfarm serve <template_id>` boots the FULL editor on localhost (disk-backed records/storage, free in-process render); edit composition.html on disk (Claude Code, Codex, etc.) and the browser live-morphs it.",
   "type": "module",
   "bin": {