CLI
Command-line tool for downloading X (Twitter) videos, and the authentication flow the MCP server uses.
Install
Requires Node.js >= 24. No global install needed — run directly with npx, or install globally:
npm install -g @roudanio/x-downloader-cliyt-dlp on your PATH for direct downloads. ffmpeg too, unless you pass -f best. Neither is required just to use the MCP server or auth commands.
Quick start
Direct downloads run your local yt-dlp — no account needed:
x-downloader https://x.com/user/status/123456789Download flags
| -o, --output <dir> | Output directory (default ~/Downloads) |
| -n, --filename <name> | Custom output filename |
| -f, --format <format> | yt-dlp format selector (default bestvideo*+bestaudio/best) |
| -F, --list-formats | List available formats and exit |
| --cookies <file> | Cookies file to pass to yt-dlp |
| --proxy <url> | Proxy URL to pass to yt-dlp |
| --dry-run | Print the resolved yt-dlp command instead of running it |
Authentication
auth login / auth logout / auth status manage a device-authorization token used by the MCP server (x-downloader-mcp) to call the website's API. The direct download command above never uses this token and never calls the website.
Exit codes
| 0 | Success |
| 1 | Generic error (bad arguments, auth failure, yt-dlp exited with an error) |
| 2 | Missing dependency (yt-dlp not found, or ffmpeg missing for the default format) |
| other | Passed straight through from the underlying yt-dlp process |
Machine-readable output
Not yet available for direct downloads — output is plain text. Use the MCP server or REST API directly if you need structured responses.