yt-ez

A zero-fuss YouTube CLI. Browse, download, and watch YouTube videos right from your terminal — powered by yt-dlp and a local Express server.

File Structure

yt-ez/
├── cli.js           ← CLI entry point  (NEW)
├── server.js        ← Web server       (MODIFIED — drop-in replacement)
├── package.json     ← Updated with bin + pkg config
├── data/
│   └── history.json
├── downloads/
└── public/
    ├── app.js
    ├── index.html
    ├── style.css
    └── watch.html

Setup

npm install

Link for local use (no packaging needed)

npm link
yt-ez help

Packaging as a standalone binary

Install pkg (dev dependency, already in package.json):

npm install

Then build:

# All platforms at once:
npm run pkg:all

# Or individually:
npm run pkg:win      # → dist/yt-ez-win.exe
npm run pkg:mac      # → dist/yt-ez-mac
npm run pkg:linux    # → dist/yt-ez-linux

Note: pkg bundles Node.js + your app code into a single executable. yt-dlp is a Python binary and cannot be bundled — it must be installed separately on the target machine (pip install yt-dlp or download from https://github.com/yt-dlp/yt-dlp/releases).

Commands

| Command | Description | |---|---| | yt-ez | Greeting + help hint | | yt-ez browse | Start server, open browser UI | | yt-ez download <url> <video\|audio> [360\|720\|1080] | Auto-trigger browser download | | yt-ez watch <url> [360\|720\|1080] | Open watch page at given quality | | yt-ez config | List all config options | | yt-ez config <setting> | Describe a specific setting | | yt-ez config <setting> <value> | Update a setting | | yt-ez clear-saves | Wipe history + cache files | | yt-ez reboot | Clear saves + reset config to defaults | | yt-ez help | Full help text |

Config settings

| Setting | Default | Description | |---|---|---| | history | ~/data/history.json | Path to history JSON file | | cache | ~/downloads | Folder for downloaded files | | save-time | 7 | Days before cached files are pruned. Use 0 for instant, none for never |

Environment Variables

The CLI passes these to server.js automatically. You can also set them manually:

| Variable | Description | |---|---| | YTEZ_HISTORY_FILE | Override history file path | | YTEZ_CACHE_DIR | Override cache directory | | CACHE_TTL_DAYS | Override cache TTL in days | | YTEZ_SAVE_TIME_NONE | Set to 1 to disable pruning | | PORT | Server port (default: 3000) | | FFMPEG_PATH | Path to ffmpeg binary dir |