IDM-CLI (CLI Internet Download Manager Clone)

IDM-CLI is a blazing-fast, multi-threaded CLI download manager built in TypeScript and optimized for the Bun runtime. Inspired by Internet Download Manager (IDM), it splits files into multiple segments and downloads them concurrently to maximize bandwidth, complete with a modern interactive prompt shell, auto-update checks, atomic state tracking, and ultra-safe chunk merging.

✨ Key Features

1. 🚀 Segmented / Concurrent Downloads: Splitting the file into up to 32 parallel streams (default 8) to download at the absolute maximum speed your bandwidth allows.
2. 💬 Interactive Shell Mode (REPL): Run the interactive shell, and it opens a persistent, visual download shell prompt where you can copy/paste links sequentially.
3. 🎭 Dynamic Quality Selection & Automated Merging (1080p, 4K):
   • When downloading YouTube/streaming videos, you are prompted with a beautiful visual menu showing all available resolutions (144p, 360p, 720p, 1080p, 2K, 4K).
   • High resolutions are downloaded concurrently (video + audio separately) and automatically merged in less than 1 second (using copy remuxing)!
4. 🔌 Zero-Setup Plug & Play Concurrency:
   • Historically, merging high-resolution videos required the user to manually install ffmpeg and configure system paths.
   • IDM-CLI solves this! It automatically downloads and caches the correct static, lightweight ffmpeg and yt-dlp binaries for your specific OS (Windows, macOS, Linux) in the background. Enjoy 1080p+ downloads out-of-the-box with zero manual configuration!
5. 🗂️ Clean Output & Temp Isolation: Downloads in progress are isolated safely into a temp_downloads/ folder. Only once a file is 100% successfully downloaded (and remuxed) is it moved to your final destination, keeping your primary downloads folder perfectly clean from broken or partial files.
6. ⏯️ Robust Pause & Resume: Supports pausing a download and resuming it exactly where it was left off using state .dl.json files.
7. 🔒 Atomic State Management: To prevent corruption in case of unexpected crashes or power outages, states are written atomically.
8. 💾 RAM-Efficient Chunk Merging: Uses $O(1)$ constant-memory buffered streaming to merge segments. Safely handles gigantic files (e.g., 10GB+) without lagging or crashing your system's RAM.
9. 🎨 Beautiful Terminal UI: Multi-progress bar dashboards built with @clack/prompts, showing connection progress, total speed, ETAs, and percentages.
10. 📋 In-Shell Sequential Download Queue: Add multiple links to a queue and run them one-by-one with the built-in queue manager.
11. 🌐 Chrome Browser Extension: Right-click any link, right-click any <video>/<audio> element, or enable Automatic Interception to redirect Chrome's downloads into IDM-CLI. A floating "Download Video" button with a quality selector is auto-injected on HTML5 video players.
12. 🔌 Local HTTP Integration Server: The interactive shell boots a daemonized HTTP server on http://localhost:18944 that the extension posts to, with a 10-slot queue, CORS, and a live status badge.

🚀 Quick Start for Users

If you are new to the command line, here is the easiest way to get started:

1. Install Bun: First, you need to install Bun. Visit their official website at bun.sh and follow the installation instructions for your operating system.

2. Install IDM-CLI globally: Once Bun is installed, open your terminal and run:

   bun install -g idm-cli

3. Start the Interactive Menu:

   idm

💡 Recommendations for the best experience:

• Always use idm: It opens a beautiful, interactive menu where you can simply paste your links. No need to memorize complicated commands!
• Install the Browser Extension: We highly recommend using our Chrome extension. It lets you download files and videos by simply right-clicking them in your browser or using the floating "Download Video" button.
• Don't worry about technical setup: IDM-CLI automatically handles all the heavy lifting (like setting up tools for video merging) in the background.

⚡ CLI Usage & Commands

Once installed, you can type idm from any terminal folder!

1. Open the Interactive Shell (Recommended)

This opens the persistent interactive prompt with a visual UI:

idm

From the interactive menu, you can select whether to download files, videos, manage queues, etc.

When the REPL starts, a small HTTP server is launched in the background on http://localhost:18944 for the Chrome extension (see Browser Extension below).

Quality Prompt

For any streaming URL, the REPL prompts you with available heights (e.g. 144p, 360p, 720p, 1080p, 2K, 4K). Anything above 720p automatically triggers the split video+audio download path with FFmpeg remuxing.

2. Standard One-Off Commands

If you prefer single-line shell commands directly:

Download a File:

idm -u https://example.com/largefile.zip

Custom Connections & Output Path:

To use 16 threads and save it to a custom directory:

idm -u https://example.com/largefile.zip -c 16 -o C:\path\to\downloads

Target a Specific Video Quality directly:

To download a YouTube video in 1080p directly:

idm -u "https://www.youtube.com/watch?v=..." -q 1080p

🌐 Chrome Browser Extension

The extension/ directory ships a Manifest V3 Chrome extension that pushes links from your browser straight into the running IDM-CLI REPL.

Install (unpacked)

1. Open chrome://extensions/ in Chrome.
2. Toggle Developer mode on (top-right).
3. Click Load unpacked and select the extension/ folder of this repo.
4. Pin the IDM-CLI Engine action icon to your toolbar for easy access.

The extension talks to the local server on http://localhost:18944 — make sure the REPL is running (idm in a terminal) so the integration server is alive. The extension icon's badge shows:

• A green #N — your link is queued at position N.
• An orange FULL — the 10-slot queue is full.
• A red OFF — the local server is unreachable.

What you can do with it

• Right-click on any link → "Download link with IDM-CLI".
• Right-click on a <video>, <audio>, or <image> element → "Download video/audio with IDM-CLI".
• Floating "Download Video" button: A small icon auto-appears in the top-right of any HTML5 <video> player (YouTube, Vimeo, direct <video> tags, etc.) when the local server is online. Hover the player to make the button appear. For YouTube/Vimeo pages the page URL is sent so yt-dlp can resolve the actual stream URLs.
• Automatic Interception: Enable the toggle in the popup. From then on, every download Chrome tries to start is cancelled and re-routed to IDM-CLI. Disable it to use Chrome's built-in downloader again.

Endpoints exposed by the local server

The REPL's background server implements:

| Method | Path | Purpose | |---|---|---| | GET | /ping | Liveness check used by the popup and content script. | | GET | /info?url=... | Returns {title, resolutions} for a streaming URL (used to populate the quality dropdown). | | GET | /queue | Returns the current queue with status (waiting / downloading). | | POST | /download | Body: {url, quality}. Enqueues a download. Returns HTTP 429 with a FULL badge if the 10-slot queue is saturated. |

CORS is enabled for localhost so the extension can call these from any page.

🛠️ Installation & Setup (For Open-Source Developers)

Ensure you have Bun installed on your system. If not, install it from bun.sh.

If you want to run or modify the codebase locally:

1. Clone the repository:

   git clone https://github.com/rj41-w2/idm-cli.git
   cd idm-cli

2. Install Dependencies:

   bun install

3. Run the Interactive CLI:

   bun start

4. Link Globally (Optional): To make the idm command available globally in your terminal:

   bun link

   Now you can just type idm from any directory!

🖥️ Standalone Bundling (Compile to .exe)

If you want to package IDM-CLI as a single standalone executable (idm.exe) that runs on any Windows machine (even if they don't have Bun or Node.js installed), you can use Bun's built-in compiler:

bun build ./index.ts --compile --outfile idm

This will generate an idm.exe file in your project folder.

• You can copy this idm.exe to a USB drive or send it to your friend.
• They don't need to install any software. They can just run it directly from their terminal or command prompt!