ydl-cli (Bun)

Tiny Bun-based CLI for your yt-dlp-api.

What this is

• ydl-cli: thin client for the API
• yt-dlp-api: backend that does actual download processing

You can use either:

• CLI (ydl ...) for convenience
• direct API (curl ...) with no CLI dependency

Requirements

• Bun is required to run this CLI.
• This package is currently Bun-first (Node-only runtime is not supported yet).

Install

Global install (recommended)

npm i -g @tomxv/ydl-cli

or

bun add -g @tomxv/ydl-cli

Local dev install

cd ydl-cli
bun link

Then ydl is available globally in your shell.

Quick Start

CLI usage

ydl "https://youtu.be/<VIDEO_ID>"
ydl "https://www.youtube.com/watch?v=<VIDEO_ID>" mp3
ydl "https://youtu.be/<VIDEO_ID>" mp4 -o myvideo.mp4
ydl "https://youtu.be/<VIDEO_ID>" source --api "https://yt-dlp-api.lugiaxetomxv.net"

Direct API usage (curl)

curl "https://yt-dlp-api.lugiaxetomxv.net/"
curl -OJ "https://yt-dlp-api.lugiaxetomxv.net/dl?url=https%3A%2F%2Fyoutu.be%2F<VIDEO_ID>"
curl -OJ "https://yt-dlp-api.lugiaxetomxv.net/dl?url=https%3A%2F%2Fyoutu.be%2F<VIDEO_ID>&format=mp3"

CLI Command Reference

ydl <url> [format] [options]
ydl help
ydl man

• url: required
• format: optional (default: source)
• --api <base>: API base URL
• -o, --output <file>: save to specific file name
• -h, --help: show help

Allowed formats:

• source, mp4, mp3, webm, m4a, flac, wav

Input Validation Behavior

The CLI validates inputs before sending any request to the API:

• Only http:// and https:// URLs are accepted.
• Unknown commands / invalid URL-like input are rejected locally.
• Unsupported format values are rejected locally.

Typical validation failures exit with code 2.

man ydl integration

• On install: man page is auto-installed (postinstall)
• On uninstall: man page is auto-removed (preuninstall)

Manual commands:

bun run install:man
bun run uninstall:man

If man ydl is not found, add this to your shell profile:

export MANPATH="$HOME/.local/share/man:${MANPATH:-}"

Support

If ydl-cli is useful to you and you want to support development:

• GitHub Sponsors: https://github.com/sponsors/TomXV

Environment Variable

• YDL_API: default API base URL

Troubleshooting

• Error: Invalid URL. Only http/https URLs are supported.
  → Check URL format and scheme.

• Error: Unsupported format '...'
  → Use one of the allowed formats.

• Error: HTTP 500 {"error":"Server runtime missing JavaScript engine required by extractor."}
  → This is an API server runtime issue (not a CLI parse issue). Check server environment.

Legal / Responsibility

• Use this tool only for content you are authorized to access/download.
• Do not use it for unauthorized copyrighted content.
• Operator/user is responsible for complying with applicable laws and platform terms.