{"id":51206137,"url":"https://github.com/dimix/mule-cli","last_synced_at":"2026-06-28T03:04:34.158Z","repository":{"id":367295754,"uuid":"1280156371","full_name":"dimix/mule-cli","owner":"dimix","description":"Search \u0026 download from the eMule (ed2k/Kad) network via a tiny CLI — headless MLDonkey in Docker, --json friendly","archived":false,"fork":false,"pushed_at":"2026-06-25T10:39:54.000Z","size":26,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-25T12:13:09.886Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dimix.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-25T10:16:38.000Z","updated_at":"2026-06-25T10:39:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dimix/mule-cli","commit_stats":null,"previous_names":["dimix/mule-cli"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/dimix/mule-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimix%2Fmule-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimix%2Fmule-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimix%2Fmule-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimix%2Fmule-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dimix","download_url":"https://codeload.github.com/dimix/mule-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimix%2Fmule-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34875388,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-28T03:04:33.668Z","updated_at":"2026-06-28T03:04:34.152Z","avatar_url":"https://github.com/dimix.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mule — search \u0026 download from eMule (ed2k / Kad) via CLI\n\nA tiny CLI that drives a headless **MLDonkey** engine (in Docker) to search and\ndownload files from the **ed2k** and **Kad** networks — with no GUI Mac app.\nEvery data command supports `--json`, so it's usable both by hand and by an agent.\n\n## Install (macOS)\n\nYou only need [Homebrew](https://brew.sh). Then:\n\n```bash\ngit clone https://github.com/dimix/mule-cli.git\ncd mule-cli\n./install.sh\n```\n\n`install.sh` does everything: installs Colima + Docker, starts the MLDonkey engine\nin a container, bootstraps Kad and the ed2k servers, and puts `mule` on your PATH.\nIt's idempotent (safe to re-run). Afterwards, from any directory:\n\n```bash\nmule search \"big buck bunny\"\nmule download \u003cid\u003e\n```\n\n## Architecture\n\n```\n  mule  (Python, host)  ──telnet 127.0.0.1:4000──▶  MLDonkey (Docker container)\n                                                        │ ed2k + Kad (serverless)\n   completed downloads  ◀── ./data/incoming/files/ ◀────┘\n```\n\n- The networking (ed2k/Kad protocol, hashing, queues, sources) is done by MLDonkey.\n- The CLI sends commands to MLDonkey's console and cleans up / parses the output.\n- Container: `mule-mldonkey` (image `carlonluca/mldonkey`, native arm64).\n- Container runtime: **Colima** (a lightweight Linux VM, installed via Homebrew).\n\n## Where files land\n\n| | path on the Mac |\n|---|---|\n| Completed | `./data/incoming/files/` |\n| Partial   | `./data/temp/` |\n| MLDonkey config | `./data/*.ini` |\n\n(`./data` is mounted as `/var/lib/mldonkey` inside the container.)\n\n## Everyday use\n\n```bash\nmule net                       # network status (is Kad connected?)\nmule search interstellar       # search (waits ~35s for Kad results)\nmule search \"big buck bunny\" --limit 15\nmule results                   # re-show the last search\nmule download 12               # download result #12 (multiple ids allowed)\nmule downloads                 # progress of active downloads\nmule pause 1 / resume 1        # pause / resume\nmule cancel 1                  # cancel (handles the confirmation itself)\nmule commit                    # move completed files into incoming/\n```\n\nEvery data command accepts `--json`:\n```bash\nmule search debian --json\nmule downloads --json\n```\n\nEscape hatch for raw MLDonkey console commands (debug / advanced):\n```bash\nmule console \"vma\"             # list all servers\nmule console \"kad_stats\"\n```\n\n## Daemon management\n\n```bash\nmule daemon status             # is it up?\nmule daemon start|stop|restart\nmule daemon logs\n```\n\n## After a Mac reboot\n\nColima does not start on its own (unless you run `brew services start colima`):\n\n```bash\ncolima start                   # restart the Linux VM\ndocker start mule-mldonkey     # the container has restart=unless-stopped\nmule net                       # check that Kad reconnects\n```\n\n## Re-bootstrapping the networks (if searches stop returning results)\n\ned2k/Kad need to be \"hooked\" to some peers. The setup already does this, but if\nKad ever stops connecting:\n\n```bash\nmule console \"kad_web\"                                   # default Kad nodes\nmule console \"urladd kad http://upd.emule-security.org/nodes.dat\"\nmule console \"force_web_infos kad\"\nmule console \"save\"\n```\n\nFor **ed2k servers**, the automatic lists (server.met) are mostly dead, so it's\nbetter to add live servers by hand with `n \u003cip\u003e \u003cport\u003e`. The ones in `servers.txt`\nwere alive 2026-06 (the first one carries ~23M files):\n\n```bash\nmule console \"n 45.82.80.155 5687\"      # eMule Security  (most loaded)\nmule console \"n 176.123.5.89 4725\"      # eMule Sunrise\nmule console \"n 91.208.162.87 4232\"     # Sharing-Devils\nmule console \"c\"                         # connect\nmule console \"save\"\n```\n\nNote: the ipfilter (`guarding.p2p`) may flag some servers as \"IP blocked\".\n\n## Notes\n\n- The ed2k/Kad network indexes **mostly media files**: queries like \"ubuntu\" often\n  return 0 results. Results are **not filtered**.\n- The classic ed2k servers are mostly dead; real downloads go through **Kad**.\n- Behind NAT without port-forwarding you get a \"LowID\": it works, but is slower.\n  For a \"HighID\", forward the container's TCP/UDP ports (19040/19044) on your router.\n- Only download content you have the right to download.\n\n## AI integrations\n\n`mule` is built to be driven by AI agents — every data command speaks `--json`.\n\n- **Claude Code** — ships a skill at `skills/mule/SKILL.md`, auto-installed to\n  `~/.claude/skills/mule/` by `install.sh`. Just ask Claude to *\"search / download X\n  from eMule\"* and it handles engine start → search → download → reporting.\n- **Claude Desktop / Codex CLI / Cursor / any MCP client** — a zero-dependency MCP\n  server lives in `mcp/server.py`, exposing the same operations as typed tools.\n  See [`mcp/README.md`](mcp/README.md) for per-client config and a `.mcpb` one-click\n  bundle for Claude Desktop.\n- **Any shell-based agent** — see [`AGENTS.md`](AGENTS.md) for the plain-CLI playbook.\n\n## Installed stack\n\n- `brew install colima docker`\n- image `carlonluca/mldonkey` (ports: 4000 console, 4080 web, 19040/19044 p2p)\n- the CLI is just `mule` (Python 3, no external dependencies)\n\n## Disclaimer / lawful use\n\n`mule-cli` is a **client** for the ed2k/Kad P2P networks — like aMule, eMule, or\nany BitTorrent client. It hosts and distributes nothing: it only talks to an\nexisting public network.\n\nResponsibility for **what** is searched and downloaded lies entirely with the\nperson using the tool. Use it only for files you have the right to download (free\nsoftware, public-domain works, your own content, or anything licensed to allow it),\nand in compliance with the copyright laws of your country. The software is provided\n\"as is\", without warranty (see `LICENSE`).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdimix%2Fmule-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdimix%2Fmule-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdimix%2Fmule-cli/lists"}