{"_id":"@aedneth/magnus-cli","name":"@aedneth/magnus-cli","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@aedneth/magnus-cli","version":"1.0.0","description":"Universal yt-dlp media downloader + Apify-driven social-capture pipeline into CKIS markdown. Agent-native, cross-platform CLI.","type":"module","license":"AGPL-3.0-or-later","author":{"name":"Eduardo Borjas","email":"eduardoa.borjas@gmail.com"},"homepage":"https://github.com/aedneth/magnus-cli#readme","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/aedneth/magnus-cli.git"},"bugs":{"url":"https://github.com/aedneth/magnus-cli/issues"},"keywords":["yt-dlp","media-downloader","youtube","tiktok","instagram","apify","cli","agent-native","mcp","obsidian"],"engines":{"node":">=20"},"bin":{"magnus":"dist/cli.js"},"main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","lint":"eslint .","format":"prettier --write .","format:check":"prettier --check .","test":"vitest run","test:watch":"vitest","prepublishOnly":"npm run build"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","apify-client":"^2.9.0","better-sqlite3":"^11.3.0","commander":"^13.0.0","env-paths":"^3.0.0","execa":"^9.4.0","picocolors":"^1.1.0","yaml":"^2.5.1","zod":"^3.23.8"},"devDependencies":{"@changesets/cli":"^2.27.9","@eslint/js":"^9.10.0","@types/better-sqlite3":"^7.6.11","@types/node":"^20.16.0","eslint":"^9.10.0","prettier":"^3.3.3","tsup":"^8.2.4","typescript":"^5.5.4","typescript-eslint":"^8.5.0","vitest":"^4.1.8"},"_id":"@aedneth/magnus-cli@1.0.0","gitHead":"ad14415445fa6134590576009d37a89b77fdee38","_nodeVersion":"20.20.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-NTv0oWLhJ+HWQSpsf/KrhKZvV/oE5mcOzHltEesVlIFlH/Q6J12Jir1dHS/bJokQrH3aeDWvzaJ0OUBhEr60mA==","shasum":"823ac2b1f0fac2a79763997bd432c9864ca6b847","tarball":"https://registry.npmjs.org/@aedneth/magnus-cli/-/magnus-cli-1.0.0.tgz","fileCount":8,"unpackedSize":545155,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIA9l5+iLP4aRCjqS2cP3akYn9OSqd6+gSj0t21DvcI7cAiEAj4m7xE2GvGO7mH/nmCcRCBQfjtv306bsxMomSxRHLI0="}]},"_npmUser":{"name":"aedneth","email":"eduardoa.borjas@gmail.com"},"directories":{},"maintainers":[{"name":"aedneth","email":"eduardoa.borjas@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/magnus-cli_1.0.0_1780501554028_0.863445721552099"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-03T15:45:53.739Z","1.0.0":"2026-06-03T15:45:54.241Z","modified":"2026-06-03T15:45:54.498Z"},"maintainers":[{"name":"aedneth","email":"eduardoa.borjas@gmail.com"}],"description":"Universal yt-dlp media downloader + Apify-driven social-capture pipeline into CKIS markdown. Agent-native, cross-platform CLI.","homepage":"https://github.com/aedneth/magnus-cli#readme","keywords":["yt-dlp","media-downloader","youtube","tiktok","instagram","apify","cli","agent-native","mcp","obsidian"],"repository":{"type":"git","url":"git+https://github.com/aedneth/magnus-cli.git"},"author":{"name":"Eduardo Borjas","email":"eduardoa.borjas@gmail.com"},"bugs":{"url":"https://github.com/aedneth/magnus-cli/issues"},"license":"AGPL-3.0-or-later","readme":"\n\n# magnus\n\n**Universal `yt-dlp` media downloader + Apify-driven social-capture pipeline — built for humans *and* terminal AI agents.**\n\n[](https://github.com/aedneth/magnus-cli/actions/workflows/ci.yml)\n[](https://www.npmjs.com/package/magnus)\n[](#license)\n[](https://nodejs.org)\n\n
\n\nMagnus does two things:\n\n1. **Download anything `yt-dlp` supports** — auto-detects the platform from a URL and\n routes the file to the right folder with the right flags. It replaces the classic\n `.bashrc` `yt()`/`yts()` shell functions.\n2. **Bulk-ingest your saved social posts** — Instagram, TikTok and YouTube — into clean,\n transcribed Obsidian/CKIS Markdown notes via Apify (native transcripts) and local\n `yt-dlp` auto-subtitles, with spend caps and resumable queues.\n\n---\n\n## Agent-native by design\n\nLike `gh` and `vercel`, **every** command works the same for a person at a terminal and\nfor an AI agent (Claude Code, Codex, Gemini CLI, Hermes, OpenClaw, OpenCode, DeepSeek) on\nLinux, macOS and Windows:\n\n- **`--json`** on every command → stable, versioned, machine-readable output on `stdout`\n (human logs go to `stderr`, so pipes stay clean).\n- **`--yes`** skips every prompt; **non-interactive by default** when there's no TTY.\n- **Deterministic POSIX exit codes** for scripting (`0` ok, `6` budget abort, …).\n- **`magnus manifest --json`** enumerates every command, flag and exit code.\n- **`magnus mcp`** runs an MCP server so agents can discover and call commands directly.\n- **stdin/stdout composable** — `cat urls.txt | magnus batch - --json | jq …`.\n\nSee [`AGENTS.md`](./AGENTS.md) for the agent integration guide.\n\n---\n\n## Install\n\n```bash\nnpm install -g @aedneth/magnus-cli\n# or: pnpm add -g @aedneth/magnus-cli\n```\n\nThe installed binary is `magnus`.\n\nMagnus shells out to **`yt-dlp`** and **`ffmpeg`** — install those too, then verify:\n\n```bash\nmagnus doctor\n```\n\n## Quickstart\n\n```bash\nmagnus \"https://music.youtube.com/watch?v=…\" # → ~/Music/YT Music/General\nmagnus \"https://www.youtube.com/watch?v=…\" # → ~/Videos/Social Media/YouTube\nmagnus audio \"https://…\" --soundtrack # → ~/Music/YT Music/Soundtracks\nmagnus batch urls.txt # one URL per line (use - for stdin)\n\nmagnus capture instagram --input ./ig_saved/ # bulk-ingest saved posts (canary-gated)\nmagnus capture instagram --watch # record what you're watching → CKIS note\nmagnus stats # download history by platform\nmagnus config list # show resolved config\n```\n\n### `capture --watch` — record what you're watching\n\nWhen you're already playing a saved reel/TikTok, `--watch` captures the\n**system-audio monitor** via [recmp3](https://github.com/aedneth/recmp3-cli),\ntranscribes it (Groq Whisper — $0 Apify), and files one CKIS note with\n`transcript_source: recmp3-whisper`:\n\n```bash\nmagnus capture instagram --watch # press ENTER when the reel ends\nmagnus capture tiktok --watch \\ # headless / scriptable\n --url https://www.tiktok.com/@user/video/123 --author user --duration 45\n```\n\nSource auto-detects the `.monitor` device; override with `--source` or\n`RECMP3_SOURCE`. Notes land in `/00-inbox/`.\n\n> **Tip:** always quote URLs containing `&`, or your shell will background the command.\n\n## Why magnus?\n\n**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.\n\n**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.\n\n**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.\n\n## Configuration\n\nConfig lives under XDG paths (`~/.config/magnus/` on Linux):\n\n- `config.json` — output folders, budget caps, vault path, defaults.\n- `.env` (chmod `600`) — secrets such as `APIFY_TOKEN`.\n- `magnus.db` (data dir) — resume queues, spend ledger, download history.\n\n```bash\nmagnus config path # print the resolved config directory\nmagnus config set capture.budgetHardCapUsd 50\n```\n\n## Roadmap\n\n- [x] **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\n- [x] **v1.0.0** — `capture --watch` (real-time recmp3 system-audio capture → CKIS notes), published to npm as `@aedneth/magnus-cli`\n- [ ] **v1.1.0** — playlist support, concurrent download pool, per-item retry with back-off\n- [ ] **v1.2.0** — capture queue management commands (drain/pause), per-actor Apify cost breakdown\n- [ ] **future** — full docs site\n\n> The interactive Ink TUI from earlier plans was dropped in favor of streaming\n> the downloader's native progress and a clean `--json` contract — see\n> `.brain/decisions/2026-06-03-no-ink-tui-streaming-stdout.md`.\n\n## License\n\nMagnus is **dual-licensed**:\n\n- **GNU AGPL-3.0-or-later** — free and open for the public. See [`LICENSE`](./LICENSE).\n If you run a modified version as a network service, you must publish your source.\n- **Commercial license** — for companies that want to integrate or resell Magnus in a\n proprietary product/service without the AGPL's source-disclosure terms.\n See [`LICENSE-COMMERCIAL.md`](./LICENSE-COMMERCIAL.md).\n\nPermissive MIT/Apache licensing is **intentionally not offered**: it would let a company\nuse and resell this work with no agreement. Commercial inquiries: **eduardoa.borjas@gmail.com**.\n\n---\n\nPart of the **Korvex** agent-native developer-tool suite.\n","readmeFilename":"README.md","_rev":"1-b76d30e87a11d360520a15ea809bde4e"}