{"id":49569420,"url":"https://github.com/yoanbernabeu/babeliocli","last_synced_at":"2026-05-03T13:06:22.860Z","repository":{"id":352435964,"uuid":"1215149850","full_name":"yoanbernabeu/babeliocli","owner":"yoanbernabeu","description":"Read-only CLI for Babelio — JSON-first, agent-friendly. No official API, so we parse the HTML.","archived":false,"fork":false,"pushed_at":"2026-04-19T15:16:36.000Z","size":45,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-19T16:32:57.905Z","etag":null,"topics":["agent-friendly","babelio","books","cli","cobra","golang","goreleaser","json","reading","scraper"],"latest_commit_sha":null,"homepage":null,"language":"Go","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/yoanbernabeu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-19T14:48:16.000Z","updated_at":"2026-04-19T15:16:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yoanbernabeu/babeliocli","commit_stats":null,"previous_names":["yoanbernabeu/babeliocli"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/yoanbernabeu/babeliocli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yoanbernabeu%2Fbabeliocli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yoanbernabeu%2Fbabeliocli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yoanbernabeu%2Fbabeliocli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yoanbernabeu%2Fbabeliocli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yoanbernabeu","download_url":"https://codeload.github.com/yoanbernabeu/babeliocli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yoanbernabeu%2Fbabeliocli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32569728,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"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":["agent-friendly","babelio","books","cli","cobra","golang","goreleaser","json","reading","scraper"],"created_at":"2026-05-03T13:06:20.767Z","updated_at":"2026-05-03T13:06:22.854Z","avatar_url":"https://github.com/yoanbernabeu.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# babeliocli — a read-only, agent-friendly CLI for Babelio\n\n[![CI](https://github.com/yoanbernabeu/babeliocli/actions/workflows/ci.yml/badge.svg)](https://github.com/yoanbernabeu/babeliocli/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Go Report Card](https://goreportcard.com/badge/github.com/yoanbernabeu/babeliocli)](https://goreportcard.com/report/github.com/yoanbernabeu/babeliocli)\n\n`babeliocli` is an unofficial, read-only command-line client for [babelio.com](https://www.babelio.com) — the French book community. It is built for shell scripting and AI coding agents: every command emits JSON by default (`-f text` is available for humans), errors go to stderr, and exit codes are meaningful.\n\nBabelio does not expose a public API, so `babeliocli` authenticates through the regular web form (or imports cookies from your browser for Google/Facebook SSO) and parses the HTML of the logged-in pages.\n\n## Features\n\n- **Read your shelves** (lus, à lire, en cours, pense-bête, abandonnés, critiqués, non critiqués) with exact counts\n- **List books** per shelf with title, author IDs, rating, reading status, start/end dates, number of readers\n- **Search** the catalogue by title, author, or free text\n- **Book details**: synopsis, publisher, number of pages, average rating, review count, genres\n- **Reviews**: paginated list of critiques with author, date (raw + ISO), rating, and full body\n- **JSON-first output**, `-f text` for a readable terminal view\n- **Classic login** (username / password) or **cookie import** for SSO-linked accounts\n- **Session file** stored under `$XDG_CONFIG_HOME/babeliocli/session.json` (mode 0600)\n- **Expired-session detection**: commands return a clear error instead of silently returning empty data\n- Proper **ISO-8859-1 → UTF-8** charset handling (Babelio still serves legacy Latin-1 HTML)\n\n## Install\n\nOne-liner (Linux / macOS, amd64 / arm64):\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/yoanbernabeu/babeliocli/main/install.sh | sh\n```\n\nThe script downloads the matching binary from the latest GitHub release and installs it to `/usr/local/bin` (override with `BABELIOCLI_INSTALL_DIR=…`).\n\nOr with Go:\n\n```bash\ngo install github.com/yoanbernabeu/babeliocli@latest\n```\n\nOr download a prebuilt binary from the [releases page](https://github.com/yoanbernabeu/babeliocli/releases).\n\n## Quick Start\n\n```bash\n# 1. Authenticate (username/password)\nbabeliocli login --username you@example.com\n\n# ...or import cookies if you sign in with Google/Facebook:\nbabeliocli session import \\\n  --phpsessid 'XXX' \\\n  --bbac 'YYY' \\\n  --id-user 'NNN' \\\n  --username 'your_pseudo'\n\n# 2. Verify\nbabeliocli whoami\n\n# 3. List shelves and books\nbabeliocli shelves -f text\nbabeliocli books --shelf lus --limit 10 -f text\n\n# 4. Search and explore\nbabeliocli search \"becky chambers\" -f text\nbabeliocli book /livres/Simmons-Les-Cantos-dHyperion-tome-1--Hyperion-1/5603 -f text\nbabeliocli reviews /livres/Simmons-Les-Cantos-dHyperion-tome-1--Hyperion-1/5603 --limit 5 -f text\n```\n\n## JSON output for scripting and agents\n\nAll commands emit JSON by default. Pipe through `jq` or consume directly from a coding agent:\n\n```bash\n# Count books read per month\nbabeliocli books --shelf lus | jq -r '.books[] | .read_end[0:7]' | sort | uniq -c\n\n# Top 10 authors across your library\nbabeliocli books --shelf all | jq -r '.books[].author' | sort | uniq -c | sort -rn | head\n\n# Get the average rating of every \"Hyperion\" search result\nbabeliocli search hyperion | jq '.results[] | {title, author, avg_rating}'\n```\n\nErrors go to stderr, so stdout stays valid JSON:\n\n```bash\nbabeliocli shelves 2\u003e/dev/null | jq '.shelves | length'\n```\n\n## Commands\n\n| Command | Description |\n|---|---|\n| `babeliocli login` | Username/password auth; stores session locally |\n| `babeliocli session import` | Import browser cookies (for Google/Facebook SSO) |\n| `babeliocli whoami` | Show the current session's user |\n| `babeliocli logout` | Delete the local session file |\n| `babeliocli shelves` | List built-in shelves with counts |\n| `babeliocli books --shelf \u003ckey\u003e` | List books in a shelf (paginated automatically) |\n| `babeliocli search \u003cquery\u003e` | Search books by title/author |\n| `babeliocli book \u003curl\\|path\\|slug/id\u003e` | Show a book's details |\n| `babeliocli reviews \u003curl\\|path\\|slug/id\u003e` | List reader reviews |\n\nSupported shelf keys: `all`, `lus`, `a-lire`, `en-cours`, `pense-bete`, `abandonnes`, `critiques`, `non-critiques`.\n\n## How It Works\n\nBabelio has no public API, so `babeliocli`:\n\n1. Posts credentials to `/connection.php?r=1` (or reuses imported cookies).\n2. Keeps the resulting `PHPSESSID`, `bbac`, `bbacml`, and `id_user` cookies in a jar, persisted to `~/.config/babeliocli/session.json`.\n3. Fetches the relevant HTML pages (`/mabibliotheque.php`, `/livres/…`, `/recherche.php`) and parses them with [goquery](https://github.com/PuerkitoBio/goquery), transcoding ISO-8859-1 on the fly.\n\nBecause parsing depends on Babelio's HTML structure, the CLI can break if the site is redesigned. Open an issue if a command stops returning data.\n\n## Responsible use\n\n- `babeliocli` is **read-only**. It does not write, rate, review, or modify your Babelio account.\n- Respect Babelio's terms of service and rate limits. Do not hammer the service: commands fetch pages sequentially at human speed.\n- This project is not affiliated with or endorsed by Babelio.\n\n## AI agent skills\n\n`babeliocli` ships with [skills](.agents/skills/) for AI coding agents (Claude Code, Cursor, Copilot). They teach the agent how to authenticate, query shelves, and produce grouped reports directly from your editor.\n\nInstall them with [skills.sh](https://skills.sh/):\n\n```bash\nnpx skills add https://github.com/yoanbernabeu/babeliocli --skill babeliocli-setup\nnpx skills add https://github.com/yoanbernabeu/babeliocli --skill babeliocli-library\nnpx skills add https://github.com/yoanbernabeu/babeliocli --skill babeliocli-discover\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and PRs welcome.\n\n## License\n\nMIT © Yoan Bernabeu\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyoanbernabeu%2Fbabeliocli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyoanbernabeu%2Fbabeliocli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyoanbernabeu%2Fbabeliocli/lists"}