{"id":28901220,"url":"https://github.com/stevenbenner/mdexsync","last_synced_at":"2026-05-04T23:34:36.993Z","repository":{"id":299309999,"uuid":"865549220","full_name":"stevenbenner/mdexsync","owner":"stevenbenner","description":" :books: MangaDex download and synchronization tool for GNU/Linux.","archived":false,"fork":false,"pushed_at":"2025-06-30T16:00:08.000Z","size":51,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-20T21:49:15.919Z","etag":null,"topics":["bash","cli","command-line","linux","mangadex","mangadex-api"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stevenbenner.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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}},"created_at":"2024-09-30T17:58:42.000Z","updated_at":"2025-07-17T21:38:11.000Z","dependencies_parsed_at":"2025-06-15T23:03:31.330Z","dependency_job_id":"6b5b83d4-7569-431b-8fb4-4c17e55fdf9b","html_url":"https://github.com/stevenbenner/mdexsync","commit_stats":null,"previous_names":["stevenbenner/mdexsync"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/stevenbenner/mdexsync","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stevenbenner%2Fmdexsync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stevenbenner%2Fmdexsync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stevenbenner%2Fmdexsync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stevenbenner%2Fmdexsync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stevenbenner","download_url":"https://codeload.github.com/stevenbenner/mdexsync/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stevenbenner%2Fmdexsync/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32628831,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-04T10:08:07.713Z","status":"ssl_error","status_checked_at":"2026-05-04T10:08:02.005Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["bash","cli","command-line","linux","mangadex","mangadex-api"],"created_at":"2025-06-21T10:08:46.252Z","updated_at":"2026-05-04T23:34:36.986Z","avatar_url":"https://github.com/stevenbenner.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mdexsync\n\n**MangaDex download and synchronization tool.**\n\nmdexsync is a program to download releases from [MangaDex][mangadex]. It will\ncreate a directory with the title of the manga in the specified download folder.\nThen it will create a subdirectory for each chapter containing the page images.\n\nThis software is licensed under the [Apache License, Version 2.0][license].\n\n[mangadex]: https://mangadex.org/\n[license]: LICENSE.txt\n\n## Features\n\nThere are many other (better, more advanced) download tools out there for\nMangaDex. However they are generally designed to have helpful user interfaces\nand only run in interactive mode. I wanted a super-simple synchronization\nprogram that I can run from scripts automatically (e.g. a script called by a\nsystemd timer or cron job). This program is designed to be simple, only command\nline interface, and easy to invoke from other scripts.\n\n * Pure CLI.\n * Non-interactive operation.\n * Designed for automation.\n * Minimal dependencies.\n * Uses the official [public API][apidocs].\n * Attempts to stay within rate limits.\n * Persistent manga titles between runs.\n * Does not re-download content you have already synced.\n * Creates a directory structure that sorts reliably.\n * Gracefully handles multiple versions of chapters.\n * Will not pollute folders with partial or failed downloads.\n * Includes some basic retry logic to handle a transitory connection failures.\n\n[apidocs]: https://api.mangadex.org/docs/\n\n## Installation\n\nThis program is written in bash and designed for use on GNU/Linux systems.\n\n### Install from tarball\n\nDownload the latest version of the script from the [releases page][releases] on\nGitHub. Extract the contents to some temporary directory. Then run the following\ncommand to install the program:\n\n```shell\nsudo make install\n```\n\nTo uninstall the program you can run the following command in the same folder:\n\n```shell\nsudo make uninstall\n```\n\n[releases]: https://github.com/stevenbenner/mdexsync/releases/latest\n\n### Dependencies\n\nThis script depends on the following programs:\n\n * [curl][curl]: (required) For HTTP communication\n * [jq][jq]:     (required) For JSON data processing\n * [diff][diff]: (required) For chapter version deduplication\n\n[curl]: https://curl.se/\n[jq]: https://jqlang.github.io/jq/\n[diff]: https://www.gnu.org/software/diffutils/\n\n## Usage\n\nYou will need the ID of the manga that you wish to download. You can find the ID\nin the URL used for the work on mangadex.org. It will be a hexadecimal GUID in\nthe format '88888888-8888-8888-8888-888888888888'.\n\n### Examples\n\nDownload first 5 chapters of Yotsuba\u0026! to the `~/Downloads` folder:\n\n * `mdexsync -p ~/Downloads -i 58be6aa6-06cb-4ca5-bd20-f1392ce451fb -m 5`\n\n### Options\n\n| Option   | Description                                                   |\n| :------- | :------------------------------------------------------------ |\n| `-p DIR` | Path to directory where downloaded content should be saved.   |\n| `-i ID`  | ID of the work to download.                                   |\n| `-m NUM` | Maximum number of chapters to download. Unlimited if omitted. |\n| `-v`     | Print verbose output.                                         |\n| `-V`     | Print version info and quit.                                  |\n| `-h`     | Print usage info and quit.                                    |\n\n## Directory structure\n\nThis script creates a deterministic folder structure to uniquely identify every\ndownload and ensure consistent sort order.\n\n * The top-level folder will be the name of the work.\n * The chapter subdirectory names will include a chapter number, with decimal,\n   release version number, associated scanlation group(s), and title (if set).\n    - Chapter number will be padded with zeros to always be at least 3 digits.\n    - The decimal will always be present, even if it is not published as a\n      fractional chapter. The decimal will be 0 in those cases (e.g. \"c001.0\").\n      This is to guarantee sort order in readers. Decimals can be more than one\n      digit long (e.g \"c040.51\").\n    - The version number is the version of that particular release. This number\n      is incremented when the owner changes something. Including it in the\n      folder name ensures that new updates get downloaded.\n    - Some chapters do not have associated groups. Those will instead be tagged\n      with the username of the user who upload it.\n    - There can be multiple groups associated with a release. In those cases the\n      groups are concatenated with an ampersand. For example:\n      \"[Group A \u0026 Group B]\"\n    - The title is often not known/set on chapters. So in those cases it will be\n      omitted from the directory name.\n * The individual page file names will be padded with zeros to be at least a\n   3-digit number.\n\n### Path text filters\n\nIn addition to the directory naming conventions outlined above, the following\ntext filters are applied in all cases:\n\n * Slashes are replaced with a unicode \"big solidus\" character (`⧸`) to preserve\n   the text and be compatible with file system naming restrictions.\n * Leading and trailing whitespace characters are removed.\n * Leading dots are removed from directory names.\n\n### Example directory tree\n```\nYotsuba\u0026!\n├── c001.0v2 [Momotato] Yotsuba \u0026 Moving\n│   ├── 001.jpg\n│   ├── 002.jpg\n│   ├── 003.jpg\n│   └── ...n\n├── c002.0v2 [Momotato] Yotsuba \u0026 Manners\n│   ├── 001.jpg\n│   ├── 002.jpg\n│   ├── 003.jpg\n│   └── ...n\n├── c003.0v2 [Momotato] Yotsuba \u0026 Global Warming\n│   ├── 001.jpg\n│   ├── 002.jpg\n│   ├── 003.jpg\n│   └── ...n\n└── ...n\n```\n\n## Persistent titles\n\nThe title of a work shown on MangaDex sometimes changes as better or more\nofficial titles come out. For a tool like this, we want the manga title to be\nconsistent between runs to avoid creating new folders and re-downloading content\nwhen a name is changed. The mdexsync script will save the title associated with\na manga ID to a persistent cache file the first time it successfully fetches it.\n\nThis file is stored in the [XDG][xdgspec] data folder at this location:\n\n * `$XDG_DATA_HOME/mdexsync/manga_index`\n\nThe XDG data folder is typically located at `~/.local/share`.\n\n[xdgspec]: https://specifications.freedesktop.org/basedir-spec/latest/\n\n### Changing the title of a downloaded work\n\nIf you would like to change the title of a manga that you have downloaded then\nyou will need to change the title in that file. Once you do that you can then\nrename the downloaded folder to match.\n\n### Backup consideration\n\nIf you backup your downloaded files then you might want to consider backing up\nthe title cache file along with them. Which would let you easily restore the\nID/title/path associations if you ever need to restore a backup.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstevenbenner%2Fmdexsync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstevenbenner%2Fmdexsync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstevenbenner%2Fmdexsync/lists"}