Skip to content

README.md

Latest commit

 

History

History
120 lines (82 loc) · 3.82 KB

README.md

File metadata and controls

120 lines (82 loc) · 3.82 KB

Fable Xport CLI

CLI tool to export your Fable.co book library via their API. Supports CSV, JSON, and Markdown output formats.

Features

  • Export to CSV (30+ columns), JSON (hierarchical), or Markdown (human-readable)
  • Comprehensive data extraction: ratings (overall + 4 detailed dimensions), reviews, reading progress, metadata
  • Per-list or combined export modes
  • StoryGraph-compatible output
  • Automatic pagination handling for large libraries
  • JWT authentication with credential caching

Installation

Clone the repo and run:

./run.bat    # Windows
./run.sh     # Mac/Linux

Uses uv to bootstrap Python environment and dependencies automatically.

Configuration

On first run, you'll be prompted for two values:

User ID: UUID from any api.fable.co request URL
Auth Token: JWT token from Authorization header (exclude the "JWT " prefix)

Extract these via browser DevTools (F12 → Network tab → inspect any Fable API call).

Credentials are stored locally in .env:

FABLE_USER_ID=your-uuid-here
FABLE_AUTH_TOKEN=your-jwt-token-here

Usage

Run the launcher script and follow the interactive prompts:

  1. Select output formats (CSV, JSON, MD)
  2. Choose export mode (separate files per list vs single combined file)
  3. Specify output directory (default: ./exports)

Export runs automatically once confirmed.

Output Formats

CSV

Tabular format with 30+ columns:

  • Book metadata: title, subtitle, authors, ISBN, publisher, pages, published date, cover URL
  • Reading data: status, started/finished dates, current page
  • Ratings: overall + characters/plot/writing/setting (1-5 scale)
  • Review data: text, spoiler flag, DNF status, liked/disliked/disagreed summaries
  • Categorization: genres, moods, content warnings, custom attributes
  • Engagement: emoji reactions, spicy level

JSON

Hierarchical structure with nested objects:

{
  "title": "Book Title",
  "rating": 4.5,
  "detailed_ratings": {
    "characters": 4.0,
    "plot": 4.5,
    "writing_style": 5.0,
    "setting": 4.0
  },
  "genres": ["Fantasy", "Adventure"],
  "started_reading": "2025-01-20"
}

Markdown

Human-readable format organized by reading status. Includes formatted ratings, metadata lists, and review text.

API Implementation

Uses Fable's v2 REST API:

  • GET /api/v2/users/{user_id}/book_lists - fetch list metadata
  • GET /api/v2/users/{user_id}/book_lists/{list_id}/books - paginated book retrieval
  • GET /api/users/{user_id}/reviews/ - rating/review data (note: v1 endpoint)

Authentication: Authorization: JWT {token} header on all requests.

Data normalization handles nested book objects and merges review data by book ID.

Troubleshooting

403 Forbidden: Token expired or malformed. Re-extract from browser and delete .env.

Missing data: Not all books have all fields. Rating dimensions only present if user rated them. Review data only present for reviewed books.

Slow exports: Expected for large libraries. ~1 min for 500 books. Progress shown per-list.

NoneType errors: Should be handled gracefully. If persist, check for data structure changes in Fable API responses.

Technical Details

Dependencies: Python 3.7+, requests, python-dotenv
Architecture: CLI orchestration layer, API client module, format-specific exporters
Error handling: Graceful degradation - partial exports succeed even with some failures
Data flow: Fetch lists → Fetch books per list → Fetch reviews → Merge by ID → Export

See TROUBLESHOOTING.md for common issues and detailed debugging steps.

License

MIT

Notes

Fable.co doesn't provide an official export feature. This tool reverse-engineers their API. May break if they change their endpoints or authentication scheme.

Credentials stored in plaintext in .env. Don't commit to version control. Add to .gitignore if forking.