{"id":50010817,"url":"https://github.com/deepghs/animedex","last_synced_at":"2026-05-19T22:45:34.892Z","repository":{"id":356211019,"uuid":"1231494701","full_name":"deepghs/animedex","owner":"deepghs","description":"A read-only, multi-source, gh-flavored CLI for anime and manga metadata, designed for humans and LLM agents. WIP.","archived":false,"fork":false,"pushed_at":"2026-05-19T04:59:11.000Z","size":8113,"stargazers_count":1,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-19T05:57:37.124Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/deepghs/animedex","language":"Python","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/deepghs.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-05-07T02:36:53.000Z","updated_at":"2026-05-18T13:25:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/deepghs/animedex","commit_stats":null,"previous_names":["deepghs/animedex"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/deepghs/animedex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepghs%2Fanimedex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepghs%2Fanimedex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepghs%2Fanimedex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepghs%2Fanimedex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deepghs","download_url":"https://codeload.github.com/deepghs/animedex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepghs%2Fanimedex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33235850,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-19T15:49:41.270Z","status":"ssl_error","status_checked_at":"2026-05-19T15:49:22.917Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":[],"created_at":"2026-05-19T22:45:34.011Z","updated_at":"2026-05-19T22:45:34.886Z","avatar_url":"https://github.com/deepghs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# animedex\n\n\u003cdiv align=\"center\"\u003e\n\n[![PyPI](https://img.shields.io/pypi/v/animedex)](https://pypi.org/project/animedex/)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/animedex)\n![PyPI - Implementation](https://img.shields.io/pypi/implementation/animedex)\n![PyPI - Downloads](https://img.shields.io/pypi/dm/animedex)\n\n![Loc](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/narugo1992/84fb1b7646cd29b1305e90e3cad6f392/raw/loc.json)\n![Comments](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/narugo1992/84fb1b7646cd29b1305e90e3cad6f392/raw/comments.json)\n[![codecov](https://codecov.io/gh/deepghs/animedex/graph/badge.svg)](https://codecov.io/gh/deepghs/animedex)\n[![Documentation Status](https://readthedocs.org/projects/animedex/badge/?version=latest)](https://animedex.readthedocs.io/en/latest/)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/deepghs/animedex)\n\n[![Code Test](https://github.com/deepghs/animedex/workflows/Code%20Test/badge.svg)](https://github.com/deepghs/animedex/actions?query=workflow%3A%22Code+Test%22)\n[![Release Test](https://github.com/deepghs/animedex/workflows/Release%20Test/badge.svg)](https://github.com/deepghs/animedex/actions?query=workflow%3A%22Release+Test%22)\n[![Badge Creation](https://github.com/deepghs/animedex/workflows/Badge%20Creation/badge.svg)](https://github.com/deepghs/animedex/actions?query=workflow%3A%22Badge+Creation%22)\n[![Package Release](https://github.com/deepghs/animedex/workflows/Package%20Release/badge.svg)](https://github.com/deepghs/animedex/actions?query=workflow%3A%22Package+Release%22)\n\n[![GitHub stars](https://img.shields.io/github/stars/deepghs/animedex)](https://github.com/deepghs/animedex/stargazers)\n[![GitHub forks](https://img.shields.io/github/forks/deepghs/animedex)](https://github.com/deepghs/animedex/network)\n![GitHub commit activity](https://img.shields.io/github/commit-activity/m/deepghs/animedex)\n[![GitHub issues](https://img.shields.io/github/issues/deepghs/animedex)](https://github.com/deepghs/animedex/issues)\n[![GitHub pulls](https://img.shields.io/github/issues-pr/deepghs/animedex)](https://github.com/deepghs/animedex/pulls)\n[![Contributors](https://img.shields.io/github/contributors/deepghs/animedex)](https://github.com/deepghs/animedex/graphs/contributors)\n[![GitHub license](https://img.shields.io/github/license/deepghs/animedex)](https://github.com/deepghs/animedex/blob/main/LICENSE)\n\n\u003c/div\u003e\n\n---\n\n\u003e A read-only, multi-source, [`gh`](https://cli.github.com/)-flavored command-line interface for anime and manga metadata, designed to be used both by humans and by LLM agents (Codex, Claude, and friends).\n\n\u003cdiv align=\"center\"\u003e\n\n![animedex demo](https://raw.githubusercontent.com/deepghs/animedex/main/docs/source/_static/gifs/hero.gif)\n\n\u003c/div\u003e\n\nDocumentation: \u003chttps://animedex.readthedocs.io/en/latest/\u003e\n\n## Why animedex?\n\nThere are a dozen public anime APIs. AniList has the cleanest GraphQL surface but degraded rate limits. Jikan scrapes MyAnimeList and is the deepest catalogue. Trace.moe identifies a scene from a screenshot. nekos.best curates SFW art. Each is great at one thing — and each speaks a different protocol, has its own rate limit, and shapes responses differently.\n\n`animedex` is one CLI (and one Python library) over all of them, with three guarantees:\n\n- **Source-attributed**: every datum on screen carries `[src: anilist]` / `[src: jikan]` / etc. There is no \"merged answer\"; you always know who told you what.\n- **Read-only by project scope**: no `add to list`, no `set score`, no upload. Auth is small, account state stays untouched.\n- **Inform, do not gate**: rate limits, content classifications, and legal greys are documented in `--help` and agent-guidance blocks; the CLI does not refuse, second-guess, or impose content filters on the user's behalf.\n\nThe CLI is a thin presentation layer over an installable Python package — anything you can run at the prompt is one `from animedex.backends.X import show` away.\n\n## What works today\n\n| Backend | High-level commands | Raw passthrough | Status |\n|---|---|---|---|\n| **AniList** (graphql.anilist.co) | `animedex anilist` — search / show / character / staff / studio / schedule / trending / user / + 20 long-tail endpoints (28 anonymous, plus 4 auth-required stubs) | `animedex api anilist '\u003cgraphql-query\u003e'` | live |\n| **Jikan v4** (api.jikan.moe; MyAnimeList view) | `animedex jikan` — 87 anonymous endpoints across anime / manga / character / person / producer / season / top / random / users / clubs / magazines / genres / watch | `animedex api jikan /anime/52991` | live |\n| **Kitsu** (kitsu.io/api/edge; JSON:API library aggregator) | `animedex kitsu` — 38 anonymous endpoints across anime / manga / characters / people / producers / mappings / streaming / categories / users | `animedex api kitsu /anime/7442` | live |\n| **MangaDex** (api.mangadex.org; scanlation aggregator) | `animedex mangadex` — 26 anonymous endpoints (search / show / feed / chapter / cover / aggregate / statistics / authors / groups / lists) plus 13 authenticated reads (`me` / `my-follows-*` / `my-history` / `my-manga-status` / `my-manga-read-markers`) | `animedex api mangadex /manga/...` | live |\n| **Danbooru** (danbooru.donmai.us; tag-DSL art catalogue) | `animedex danbooru` — 57 anonymous endpoints (search / post / artist / tag / pool / count / autocomplete / iqdb-query / wiki / forum / commentary / votes / versions / moderation / operational) plus 2 authenticated reads (`profile` / `saved-searches`) | `animedex api danbooru /posts.json` | live |\n| **Waifu.im** (api.waifu.im; SFW + NSFW art) | `animedex waifu` — 9 anonymous endpoints (`tags` / `images` / `artists` / per-id + per-slug lookups / `stats-public`) plus 1 authenticated read (`me`) | `animedex api waifu /images?...` | live |\n| **Trace.moe** (api.trace.moe) | `animedex trace` — search by image (`--url` or `--input \u003cbytes\u003e`), `quota` | `animedex api trace /me` | live |\n| **Studio Ghibli API** (ghibliapi.vercel.app; bundled snapshot) | `animedex ghibli` — offline films / people / locations / species / vehicles with local filters | `animedex api ghibli /films` | offline high-level; live passthrough |\n| **AnimeChan** (api.animechan.io/v1; quotes) | `animedex quote` — random quote / filtered random / paginated quote lists / anime info, cached by default for the 5 req/hour free tier | `animedex api quote /quotes/random` | live |\n| **Shikimori** (shikimori.io; REST + GraphQL catalogue) | `animedex shikimori` — anime / manga / ranobe / clubs / publishers / top-level people / calendar / screenshots / videos / characters / staff / similar / related / external-links / topics / studios / genres | `animedex api shikimori \u003cpath\u003e` | live |\n| **ANN Encyclopedia** (cdn.animenewsnetwork.com; XML) | `animedex ann` — show / search / reports with typed XML warning handling | `animedex api ann \u003cpath\u003e` | live |\n| MAL v2 | — | — | not yet implemented |\n\nThe `animedex api \u003cbackend\u003e` passthrough is wired for twelve backends. Every passthrough call honours the project's physical transport contracts: rate limits, default `User-Agent` injection, the MangaDex `Via`-header strip, cache eligibility for known reads, and debug redaction. Method/path choices are forwarded verbatim; the caller owns the upstream result.\n\n## Try it in 30 seconds\n\n```bash\npip install -e .\n\n# AniList: GraphQL fetch + jq projection on the result\nanimedex anilist show 154587 --jq '.title.romaji'\n# =\u003e \"Sousou no Frieren\"\n\n# Jikan: MyAnimeList full record\nanimedex jikan show 52991 --jq '.data.title'\n# =\u003e \"Sousou no Frieren\"\n\n# Trace.moe: identify a scene\nanimedex trace search --url 'https://i.imgur.com/zLxHIeo.jpg' --anilist-info --jq '.[0].anilist_title.romaji'\n\n# nekos.best: SFW image grab\nanimedex nekos image husbando --jq '.[0].url'\n\n# Ghibli: bundled offline snapshot\nanimedex ghibli films --director \"Hayao Miyazaki\" --min-rt-score 95 --jq 'map(.title)'\n\n# AnimeChan: quote lookup with local cache\nanimedex quote quotes-by-character Saitama --jq '.[0] | {quote: .content, anime: .anime.name}'\n```\n\nEach command auto-switches between TTY (human-readable, source-marked) and JSON (when piped, when `--json` is set, or when `--jq` is set), respects the per-upstream rate limit (visibly: e.g., AniList's degraded 30 req/min, nekos.best's 200 req/min), and caches successful responses in a local SQLite at `~/.cache/animedex/`. Pass `--no-cache` to bypass.\n\n## Documentation\n\nThe full documentation lives at \u003chttps://animedex.readthedocs.io/en/latest/\u003e. Notable pages:\n\n- **Quickstart** — five progressive examples that cover TTY rendering, `--json`, `--jq`, `--no-cache`, and the Python library.\n- **Tutorials** — systematic per-backend deep-dives (anilist / ann / jikan / kitsu / mangadex / danbooru / waifu / ghibli / quote / trace / nekos / shikimori), the raw passthrough (`animedex api`), output modes, the `Config` Python entry point, and the `--agent-guide` flag for LLM agents.\n- **API reference** — auto-generated from the source docstrings.\n\n## Human Agency Principle (the top rule)\n\n\u003e **The human user has full choice. Whatever the consequences of that choice, they are the user's. animedex's job is to inform and to warn, not to gate, refuse, or override.**\n\nThis rule supersedes every other design guideline. Concretely:\n\n- No content filters injected on the user's behalf. If you ask Danbooru for explicit tags, you get explicit results.\n- No `--unsafe`, `--nsfw`, `--allow-...`, `--force` flags. Those exist purely to ask \"are you sure?\" and that is paternalism.\n- No double-confirmation prompts. If a command name says it does something, running the command does that thing.\n- We do warn — in `--help` text and per-command agent-guidance blocks — about every upstream whose legal posture, content class, or rate ceiling the user might want to be aware of. The warning is informational; it never blocks.\n\nLLM agents read the same docstrings; their alignment training does the rest.\n\nThe only constraints `animedex` enforces unilaterally are **technical contracts**: the rate limits the upstream actually punishes, the default headers needed for normal operation, and MangaDex's forbidden `Via` header. Those are physics, not preferences.\n\n## Repository map\n\n```\nanimedex/                Installable package (the runtime)\n  api/                     Raw passthrough dispatcher + per-backend modules\n  backends/                High-level Python API per backend (anilist, ann, ghibli, quote, shikimori, ...)\n  cache/                   SQLite TTL cache\n  config/                  Build metadata + Config entry point\n  diag/                    selftest runner + per-module smokes\n  entry/                   Click command tree (anilist, ann, ghibli, quote, shikimori, trace + api)\n  models/                  Cross-source common types (Anime, Character, ArtPost, ...)\n  policy/                  Docstring lint + agent-guide extractor\n  render/                  TTY / JSON / raw / jq / field-projection renderers\n  transport/               HTTP client + ratelimit + advisory method classifier + UA\ntest/                    Unit tests + 700+ fixture YAMLs (test/fixtures/)\nplans/                   Staged design documents (binding for contributors)\ndocs/                    Sphinx source -\u003e https://animedex.readthedocs.io\ntools/                   Fixture capture, build helpers\nAGENTS.md                Repository policy (English-only, commit identity, naming discipline)\nCLAUDE.md                Symlink to AGENTS.md\n```\n\n## Install\n\n```bash\npip install -e .\n```\n\nPyPI publication will follow once the project clears the v0.1.0 milestone (see the [master tracking issue](https://github.com/deepghs/animedex/issues/1) for the full roadmap).\n\n## How to navigate\n\n**As a contributor:** read [`AGENTS.md`](./AGENTS.md) first (it states the binding policies — English-only repository content, commit-identity rules, naming discipline, test discipline, the lossless rich-model contract); then [`plans/README.md`](./plans/README.md) for the design rationale.\n\n**As an LLM agent shelling out:** the per-command Agent Guidance blocks are extracted by `animedex --agent-guide`; that single invocation is enough to populate your tool catalogue. The blocks describe each command's content classification (NSFW posture, age-of-consent considerations), rate ceilings, and the right reflexes when the user has not explicitly asked for mature content. Read [`plans/02-design-policy-as-docstring.md`](./plans/02-design-policy-as-docstring.md) for the full rationale.\n\n## License\n\nApache License 2.0. See [`LICENSE`](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeepghs%2Fanimedex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeepghs%2Fanimedex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeepghs%2Fanimedex/lists"}