dwnld-any

Portable agent skill + local CLI for downloading videos from 8 platforms via yt-dlp. No cloud deploy — everything runs on your machine.

Platforms

Platform	Cookies	Notes
YouTube	Optional	Cookies help with bot checks
Instagram	Required	Must export browser cookies
LinkedIn	No	Public posts only
Reddit	Optional	Impersonation + optional cookies; video posts only
Loom	No	Usually works
Vimeo	No	Usually works
9GAG	No	Usually works
X (Twitter)	Optional	Public tweets usually work

---

Requirements

• Python 3.12+
• ffmpeg — brew install ffmpeg (macOS)
• yt-dlp — installed automatically with this package

---

Install

git clone https://github.com/SomSamantray/dwnld-any.git
cd dwnld-any
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

First-run setup (recommended)

python -m dwnld setup

This will:

1. Check Python version (and offer brew install python@3.12 on macOS with --install-python)
2. Create .venv and install dependencies
3. Check for ffmpeg and yt-dlp
4. Show cookie status for Instagram, YouTube, Reddit, and X

If Python is missing:

# macOS with Homebrew
brew install python@3.12
python -m dwnld setup --install-python   # or let the agent run this

---

Cookie setup

Instagram requires cookies. See the full guide: docs/cookie-setup.md

Quick version:

mkdir -p ~/.config/dwnld-any/cookies
# Export Netscape cookies from browser → instagram.txt
export YTDLP_COOKIES_INSTAGRAM=~/.config/dwnld-any/cookies/instagram.txt
python -m dwnld setup   # verify "instagram … ready"

Optional for YouTube, Reddit, X:

export YTDLP_COOKIES_YOUTUBE=~/.config/dwnld-any/cookies/youtube.txt
export YTDLP_COOKIES_REDDIT=~/.config/dwnld-any/cookies/reddit.txt
export YTDLP_COOKIES_X=~/.config/dwnld-any/cookies/x.txt

Add these to ~/.zshrc so they persist across sessions.

For X, you can instead set X_AUTH_TOKEN and X_CT0 directly (both required together) instead of exporting a cookies.txt file — see docs/cookie-setup.md.

---

Commands

# Verify environment
python -m dwnld check

# First-run / cookie status
python -m dwnld setup
python -m dwnld setup --json          # machine-readable

# Preview a URL (no download)
python -m dwnld metadata "https://www.youtube.com/watch?v=..."

# Download
python -m dwnld download "URL" --quality 1080p --format mp4 -o ~/Downloads/dwnld-any

# Smoke test all platforms (metadata)
python -m dwnld test-urls
python -m dwnld test-urls --download   # full download test

Download options

Flag	Values	Default
--quality	360p, 480p, 720p, 1080p, 4k, 8k_plus	1080p
--format	mp4, webm, mp3, gif	mp4
--audio-mode	audio_and_video, audio_only, mute_video	audio_and_video
-o	output directory	~/Downloads/dwnld-any

---

Agent skill

Attach SKILL.md in Cursor, Claude Code, or Codex. Clone to your skills folder:

git clone https://github.com/SomSamantray/dwnld-any.git ~/.cursor/skills/dwnld-any
cd ~/.cursor/skills/dwnld-any && pip install -e .

Agent first-run workflow:

1. python -m dwnld setup — if Python missing, install via Homebrew (--install-python on macOS)
2. If Instagram cookies missing → walk user through docs/cookie-setup.md; never ask for cookie values in chat, only file paths
3. python -m dwnld metadata "<url>" — confirm platform/title
4. python -m dwnld download "<url>" — report absolute file path from JSON output

---

Project layout

dwnld-any/
├── SKILL.md              # Agent instructions
├── dwnld/
│   ├── cli.py            # check, setup, metadata, download, test-urls
│   ├── setup.py          # Python/venv/cookie onboarding
│   ├── cookies.py        # Cookie file loading
│   ├── platforms.py      # Platform detection
│   ├── reddit.py         # /s/ short URL resolution
│   └── ytdlp_args.py     # --impersonate chrome for Reddit/9GAG
├── docs/
│   ├── cookie-setup.md   # Step-by-step cookie export guide
│   └── platforms.md      # Per-platform notes
└── tests/

---

Tests

source .venv/bin/activate
pytest

---

Troubleshooting

Problem	Solution
Python X.X is too old	Install 3.12+: brew install python@3.12
Missing ffmpeg	brew install ffmpeg
Missing yt-dlp	pip install -e . inside activated venv
Instagram empty media	Re-export cookies — see cookie-setup.md
Reddit 429 / timeout	Add Reddit cookies; ensure post has video
YouTube bot check	Add YouTube cookies

---

License

Personal use. Respect platform terms of service and copyright. Downloads stay on your machine.