magnus

Universal yt-dlp media downloader + Apify-driven social-capture pipeline — built for humans and terminal AI agents.

Magnus does two things:

1. Download anything yt-dlp supports — auto-detects the platform from a URL and routes the file to the right folder with the right flags. It replaces the classic .bashrc yt()/yts() shell functions.
2. Bulk-ingest your saved social posts — Instagram, TikTok and YouTube — into clean, transcribed Obsidian/CKIS Markdown notes via Apify (native transcripts) and local yt-dlp auto-subtitles, with spend caps and resumable queues.

---

Agent-native by design

Like gh and vercel, every command works the same for a person at a terminal and for an AI agent (Claude Code, Codex, Gemini CLI, Hermes, OpenClaw, OpenCode, DeepSeek) on Linux, macOS and Windows:

• --json on every command → stable, versioned, machine-readable output on stdout (human logs go to stderr, so pipes stay clean).
• --yes skips every prompt; non-interactive by default when there's no TTY.
• Deterministic POSIX exit codes for scripting (0 ok, 6 budget abort, …).
• magnus manifest --json enumerates every command, flag and exit code.
• magnus mcp runs an MCP server so agents can discover and call commands directly.
• stdin/stdout composable — cat urls.txt | magnus batch - --json | jq ….

See AGENTS.md for the agent integration guide.

---

Install

npm install -g @aedneth/magnus-cli
# or: pnpm add -g @aedneth/magnus-cli

The installed binary is magnus.

Magnus shells out to yt-dlp and ffmpeg — install those too, then verify:

magnus doctor

Quickstart

magnus "https://music.youtube.com/watch?v=…"     # → ~/Music/YT Music/General
magnus "https://www.youtube.com/watch?v=…"       # → ~/Videos/Social Media/YouTube
magnus audio "https://…" --soundtrack            # → ~/Music/YT Music/Soundtracks
magnus batch urls.txt                            # one URL per line (use - for stdin)

magnus capture instagram --input ./ig_saved/     # bulk-ingest saved posts (canary-gated)
magnus capture instagram --watch                 # record what you're watching → CKIS note
magnus stats                                     # download history by platform
magnus config list                               # show resolved config

capture --watch — record what you're watching

When you're already playing a saved reel/TikTok, --watch captures the system-audio monitor via recmp3, transcribes it (Groq Whisper — $0 Apify), and files one CKIS note with transcript_source: recmp3-whisper:

magnus capture instagram --watch                 # press ENTER when the reel ends
magnus capture tiktok --watch \                  # headless / scriptable
  --url https://www.tiktok.com/@user/video/123 --author user --duration 45

Source auto-detects the .monitor device; override with --source or RECMP3_SOURCE. Notes land in <vault>/00-inbox/.

Tip: always quote URLs containing &, or your shell will background the command.

Why magnus?

vs raw yt-dlp: Every platform needs different flags, different output paths, and different post-processing. Magnus encodes those rules once — music.youtube.com always goes to ~/Music/YT Music/, YouTube video always goes to ~/Videos/Social Media/YouTube/, TikTok always strips the watermark — so you type one command and get the right file, in the right place, every time. It also wraps every operation in a clean JSON envelope, making yt-dlp-backed workflows scriptable and CI-safe.

vs browser extensions: Browser extensions are one-at-a-time, TTY-dependent, and invisible to scripts and agents. Magnus runs headless, accepts URLs from stdin, and pipelines into jq, shell scripts, Claude Code, and CI jobs. cat urls.txt | magnus batch - --json is a valid production command.

vs manual Apify runs: Apify's web UI has no spend controls, no resume capability, and returns raw JSON with no rendering. Magnus adds a $40-abort / $50-hard-cap canary gate, per-platform SQLite resume queues (restart any run from where it stopped), and renders results directly into CKIS/Obsidian Markdown — one command from saved posts to vault notes.

Configuration

Config lives under XDG paths (~/.config/magnus/ on Linux):

• config.json — output folders, budget caps, vault path, defaults.
• .env (chmod 600) — secrets such as APIFY_TOKEN.
• magnus.db (data dir) — resume queues, spend ledger, download history.

magnus config path            # print the resolved config directory
magnus config set capture.budgetHardCapUsd 50

Roadmap

• v0.1.0 — download core (ordered platform detection, audio/video flag sets, output-folder map), Apify capture pipeline (SQLite queues, canary, spend caps, CKIS Markdown), full agent-native layer (--json, --yes, manifest, MCP server), dual AGPL-3.0 + commercial license
• v1.0.0 — capture --watch (real-time recmp3 system-audio capture → CKIS notes), published to npm as @aedneth/magnus-cli
• v1.1.0 — playlist support, concurrent download pool, per-item retry with back-off
• v1.2.0 — capture queue management commands (drain/pause), per-actor Apify cost breakdown
• future — full docs site

The interactive Ink TUI from earlier plans was dropped in favor of streaming the downloader's native progress and a clean --json contract — see .brain/decisions/2026-06-03-no-ink-tui-streaming-stdout.md.

License

Magnus is dual-licensed:

• GNU AGPL-3.0-or-later — free and open for the public. See LICENSE. If you run a modified version as a network service, you must publish your source.
• Commercial license — for companies that want to integrate or resell Magnus in a proprietary product/service without the AGPL's source-disclosure terms. See LICENSE-COMMERCIAL.md.

Permissive MIT/Apache licensing is intentionally not offered: it would let a company use and resell this work with no agreement. Commercial inquiries: eduardoa.borjas@gmail.com.

---

_{Part of the Korvex agent-native developer-tool suite.}