Hardcover Bookshelf#

Use this skill to treat Hardcover as a conversational bookshelf assistant.

It is optimized for prompts like:

• what's on my reading list
• i started reading the complete maus
• i finished reading dune
• how many books did i read last year

Required Environment#

Require HARDCOVER_TOKEN before making API calls.

Token format is Option A: the env var must contain the full Authorization header value exactly as copied from Hardcover, including the Bearer prefix.

Example:

bash

export HARDCOVER_TOKEN='Bearer eyJ...'

If missing or malformed, stop and ask the user to set it correctly.

Commands#

Run these from the skill's root directory. Pass --json for machine-readable output.

bash

npx tsx src/cli.ts list [--limit 20] [--json]
npx tsx src/cli.ts start --title "The Complete Maus" [--json]
npx tsx src/cli.ts finish --title "The Complete Maus" [--json]
npx tsx src/cli.ts count-last-year [--json]

These commands call the local TypeScript client in src/ and centralize auth, schema quirks, and error handling.

Intent mapping#

"What's on my reading list?"#

Interpret reading list as Want to Read.

Run:

bash

npx tsx src/cli.ts list

Return a clean bullet list and mention the total shown.

"I started reading "#

Run:

bash

npx tsx src/cli.ts start --title "<book>"

Behavior:

• checks currently-reading shelf first for an exact normalized title match
• falls back to Hardcover search
• if ambiguous, the command returns numbered choices; ask the user to choose before mutating
• if already currently reading, it returns the existing entry instead of creating a duplicate

"I finished reading "#

Run:

bash

npx tsx src/cli.ts finish --title "<book>"

Behavior:

• resolves the title the same way as start-reading
• prefers an existing currently-reading entry for that book
• otherwise updates the most recent existing user_book for that book
• sets status to Read and uses last_read_date as the finish-date field

Note: this is a best-effort implementation based on the live schema tested so far. If Hardcover later exposes a better canonical finish-date field for user books, update the client and references.

"How many books did I read last year?"#

Run:

bash

npx tsx src/cli.ts count-last-year

Behavior:

• computes the previous calendar year in UTC
• counts books with status_id=3 and last_read_date inside that year
• returns the total plus a small verification sample

Safety & ambiguity rules#

• Never mutate when title resolution is ambiguous.
• If the command prints multiple choices, ask the user to choose.
• Prefer concise numbered disambiguation.
• Echo the final title and state change after successful writes.

Files#

• src/client.ts — Hardcover API client and common operations
• src/cli.ts — unified CLI entrypoint
• references/schema-quirks.md — live notes on auth, status IDs, and mutation/query quirks