Alchemux
Magically intuitive CLI for yt-dlp & FFmpeg — download, convert, and optionally upload to S3 or GCP.
Interactive terminal alchemy for YouTube and 1,000+ media sources.
About
Alchemux is a terminal-first media CLI built on yt-dlp and system FFmpeg. It wraps complex download and conversion workflows in an interactive wizard, batch mode, optional cloud upload, and arcane (or plain) terminal output.
- Distribution: PyPI — install with uv (
uv tool install/uvx) - Platforms: macOS, Linux, Windows (shell + Python 3.12+)
- Config: Per-user TOML via
alchemux setup— no manual file editing required - Status: Pre-release — bugs and limitations are expected; see docs/known-issues.md
Features
- 🎵 Download & Convert Media: Extract audio or video from YouTube, Facebook, and other yt-dlp supported sources
- 🧙♂️ Interactive Simplicity: Delightfully easy terminal UI—just run and follow prompts; configure everything in seconds (including cloud storage and presets) interactively
- 📋 Batch Processing: Process many URLs from a YouTube playlist, TXT/CSV files, or pasted lists of URLs with automatic rate-limit mitigation logic built-in. See commands.md for batch mode details
- 🏷️ Metadata Embedding: Automatically embeds source URLs and metadata into media files
- ☁️ Cloud Storage: Upload media to S3 and GCP buckets after interactive setup (commands.md)
- 🎚️ Multiple Formats: Audio (MP3, AAC, FLAC, Opus, WAV, etc.) and video (MP4, MKV, WebM, etc.)
- 🤖 AI Agent Support: CLI guidance for agents like OpenClaw, Agent Zero, and Claude Skills — see backend/AGENTS.md
- 🛠️
configCommand: Interactive wizard for formats, cloud credentials, download folder, batch defaults, and more - 🩺
doctorCommand: Diagnose cloud misconfigurations, missing FFmpeg, permissions, and common failures - ⟁
scry/inspect: Inspect a sealed media file (ffprobe + embedded tags + Metadata Health); see commands.md - ✨ Arcane Interface: Optional stylized output (disable with
arcane_terms = "false"or during setup) - 🔄
updateCommand: Refresh the bundled yt-dlp dependency from the community release channel
Full command reference: docs/commands.md.
Quick Start
Prerequisites
- Shell: Terminal (macOS/Linux) or PowerShell (Windows)
- uv: Astral’s uv — one-time install below
- FFmpeg: Required (
ffmpeg+ffprobeon PATH) — docs/install.md § Install FFmpeg
Install from PyPI (recommended)
Installing with uv avoids macOS Gatekeeper and Windows SmartScreen prompts that often affect downloaded executables.
1) Install uv (one-time)
macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Verify: uv --version
2) Install as a persistent CLI tool
uv tool install alchemux
alchemux setup
alchemux "https://youtu.be/…"
amx is a short alias for the same CLI (amx "https://…").
Want to try without installing?
uvx alchemux --help uvx alchemux "https://youtu.be/…"
3) Upgrade / uninstall
uv tool upgrade alchemux
uv tool uninstall alchemux
Tip: If
uv tool upgrade alchemuxfails or you still see an older version, uninstall and install cleanly:uv tool uninstall alchemux uv tool install alchemux
Run from source (development)
For unreleased or experimental features:
git clone https://github.com/bmurrtech/alchemux.git
cd alchemux
uv pip install -e .
uv run alchemux --help
uv run alchemux setup
See docs/install.md for platform-specific FFmpeg and config paths.
Arcane terms
Alchemux can use arcane-themed wording (transmute, distill, seal, etc.). Prefer plain terms? Set arcane_terms = "false" in config.toml or choose technical mode during alchemux setup. Legend: docs/legend.md.
Known issues
Alchemux is pre-release. Documented limitations, workarounds, and what to check before filing a report: docs/known-issues.md.
Troubleshooting
alchemux -h
amx -h # available after `uv tool install alchemux`
alchemux doctor
| Problem | Solution |
|---|---|
| Config not found | Run alchemux setup or alchemux doctor — paths in docs/install.md |
| Downloads fail | Try audio-only or --flac; run alchemux update; see known-issues.md (KI-002, KI-003) |
ffmpeg not found |
Install system FFmpeg (brew install ffmpeg, apt install ffmpeg, etc.) — docs/install.md |
Contributing
Bug reports, feature requests, and feedback are welcome via GitHub Issues. Please read docs/known-issues.md first.
How to contribute (including local tooling, tests, CI, and AI-assisted PRs): CONTRIBUTING.md. AI pull request rules: AI-POLICY.md. Release process: docs/release.md.
Support open source
If Alchemux saves you time, consider:
- ⭐ Starring the repo —
- 🐛 Open a GitHub Issue — bugs, ideas, and feedback
- 📣 Sharing with others who download or archive media from the terminal
- ☕ Buy Me a Coffee or Ko-fi
Acknowledgements
- yt-dlp — core downloader
- FFmpeg — audio/video conversion (system install)
- uv — install and run via
uv tool install/uvx - prek — pre-commit hooks in CI and locally
- PyPI — package distribution
- Typer, Rich, InquirerPy — CLI UX
- pyperclip, mutagen, python-dotenv — clipboard, metadata, env helpers
License
This repository is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). The badge links to the official license text; the LICENSE file in this repo is the binding copy.
License permissions and restrictions
Keeping open-source open.
| Use case | Permitted | Notes / conditions |
|---|---|---|
| Private / internal use | ✅ | No obligation to publish changes if you do not distribute or offer the software as a network service to others. |
| Modify for own private use | ✅ | Obligations attach when you distribute or run modified code as a networked service for users. |
| Share / distribute (unmodified) | ✅ | Include AGPL license and corresponding source (or compliant written offer). |
| Distribute with modifications | ✅ | Modified source must be available under AGPL-3.0 to recipients. |
| Provide as SaaS / network service | ✅ | Users interacting with your modified version over a network must be able to obtain complete corresponding source. |
| Closed / proprietary redistribution | ❌ | Public distribution or SaaS without corresponding source under AGPL is not allowed. |
| Restricting source access for users you serve | ❌ | Network users must be able to get complete corresponding source as AGPL defines. |
| Sublicensing under more restrictive terms | ❌ | AGPL terms must flow through. |
Commercial / proprietary licensing
Need use without AGPL copyleft (closed-source distribution, SaaS without source-offer obligations, etc.)? Commercial licenses may be available. Open a GitHub Issue to discuss licensing and pricing.
Disclaimer
This software is provided as-is, without warranty of any kind. The author(s) are not liable for damages or losses from use of this project, including data loss, failed downloads, or cloud storage misconfiguration.
By using Alchemux you accept responsibility for:
- Complying with this license and the terms of service of sites you download from (e.g. YouTube)
- Ensuring yt-dlp, FFmpeg, and cloud provider usage comply with their respective licenses and policies
- Securing your own credentials for S3/GCP and local config files
Metadata
Release files for alchemux 0.1.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| alchemux-0.1.7.tar.gz | 139.0 kB | With provenance | Details for alchemux-0.1.7.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| alchemux-0.1.7-py3-none-any.whl | Python 3 | none | any | Details for alchemux-0.1.7-py3-none-any.whl |
Total release size: 310.1 kB
Release files / alchemux-0.1.7.tar.gz
| Download URL | alchemux-0.1.7.tar.gz |
|---|---|
| Size | 139.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
547c5264dcf1f71e569510920b49709ffb5f4371d82b4319c04a59e9912ee034
|
|
BLAKE2b-256 checksum How to use checksums |
d7413c4cff9ceef4e23729f19577bae9343f756d671d7330b9337fe4c43087b1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.
Transparency logRelease files / alchemux-0.1.7-py3-none-any.whl
| Download URL | alchemux-0.1.7-py3-none-any.whl |
|---|---|
| Size | 171.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3c0b2aa6e53dc70879502a783b8d65b2d0d8c84539fe6e800df71079a6fdb788
|
|
BLAKE2b-256 checksum How to use checksums |
08293fe555b4d93a63508e3f1210803da839435226b21d7ca24c558231dc04f8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.
Transparency logSecurity for alchemux 0.1.7
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for alchemux-0.1.7.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.