CLI Reference

Your bookshelf, from the terminal.

The Spine CLI is a single-file command-line tool that talks to the same API as the mobile app. Search the catalog, shelve books, rate them, and pull recommendations from your reading companion — all without leaving your terminal.

Overview

Every command returns plain text, color-coded where it helps, and accepts book titles as natural strings. Anywhere you pass a <title>, the CLI resolves it against your catalog or runs a lookup, so you don't need to hunt for IDs.

The tool is a single TypeScript entrypoint. Run it with bun or compile with bun build and alias spine to it.

Install

You'll need Bun (1.0+) or Node 18+. The CLI ships as a single file in apps/cli/src/index.ts.

# clone the CLI source (private beta access required)
$ git clone git@github.com:Jbern16/spine.git
$ cd spine/apps/cli

# run without installing
$ bun src/index.ts search "piranesi"

# or alias globally
$ alias spine="bun $(pwd)/src/index.ts"

Beta access. The CLI lives in the private Spine repo during beta. Request access by joining the Discord and messaging in #developer-access.

Configure

The CLI reads its API key from either ~/.spine.json or the SPINE_API_KEY environment variable. The env var takes precedence.

{
  "apiKey": "sk_spine_abc123...",
  "apiUrl": "https://spine-api.fly.dev"
}

Or via environment variables:

$ export SPINE_API_KEY=sk_spine_...
$ export SPINE_API_URL=https://spine-api.fly.dev  # optional, this is the default

Generating a key

Open the Spine mobile app, go to Settings → API Key, and tap Generate. Your key starts with sk_spine_ and is shown once — copy it before dismissing the screen.

One key per user. Generating a new key rotates the previous one — any existing CLI or MCP setup using the old key stops working immediately. Save it to ~/.spine.json or your secrets manager; it won't be shown again.

To revoke access entirely, open Settings → API Key and delete it, or DELETE /users/me/api-key against the API.

First run

$ spine search "the dispossessed"
  The Dispossessed by Ursula K. Le Guin (9780061054884)
  The Dispossessed by Ursula K. Le Guin (9780062823403)
  ...

$ spine add "the dispossessed" --status reading
  ✓ Added to shelf as reading

$ spine ask "the dispossessed"
  This will surprise you because it sounds political, but what
  it actually is is a portrait of a man who is an outsider on
  every world he ever stands on...

Reading

Commands for finding books in the catalog and looking up metadata.

spine search <query> alias: s

Search books by title, author, or keyword. Returns up to ten matches with ISBN.

query string · required Search term. Quote multi-word queries.

$ spine search "dune frank herbert"

spine book <title> alias: b

Full book details: author, publisher, page count, year, series info, moods, ISBN, description.

$ spine book "project hail mary"

spine author <name>

Author profile: bio, birth/death years, complete bibliography, and series.

$ spine author "Ursula K. Le Guin"

spine series <title>

If a book belongs to a series, returns the series name and every book in reading order.

$ spine series "the name of the wind"

spine similar <title>

Books similar to a given title, using catalog metadata and the recommendation model.

$ spine similar "the seven husbands of evelyn hugo"

spine moods

Lists every mood category you can browse by (Cozy & Comforting, Dark & Brooding, Strange & Unsettling, and so on).

$ spine moods

spine resolve <title>

Checks whether a book is already in the Spine catalog. Returns the book ID if found.

$ spine resolve "dune"

Shelf

Manage your bookcase: which books you own, which you're reading, and how they landed.

spine shelf alias: ls

Displays your bookcase with status (color-coded) and rating emoji.

--status string · default: all Filter by read, reading, want, or all.
--limit number · default: 20 How many entries to return (1–500).

$ spine shelf --status reading --limit 10

spine add <title>

Adds a book to your bookcase. If it's not in the catalog yet, the CLI resolves it via search.

--status string · default: want want, reading, or read.
--rating string · optional Only valid with --status read: loved, liked, or disliked.

$ spine add "the midnight library" --status reading

spine rate <title> <rating>

Rates a book and marks it as read if it wasn't already. Ratings are loved, liked, or disliked.

$ spine rate "project hail mary" loved

spine remove <title> alias: rm

Removes a book from your bookcase entirely. This is permanent.

$ spine remove "twilight"

spine review <title> <text>

Posts a short review (max 280 characters) for a book on your shelf.

$ spine review "project hail mary" "Amazing hard sci-fi with humor and heart"

Recommendations

See what your companion picked, ask it to explain a book, or dismiss something that doesn't fit.

spine recs alias: r

Your current recommendations with companion reasoning next to each title.

$ spine recs

spine featured alias: f

Today's single featured pick — the one your companion wants to surface above the others.

spine ask <title> alias: a

Ask your companion why you might love a book, how it connects to your taste, and any caveats.

$ spine ask "the seven husbands of evelyn hugo"

spine dismiss <title> alias: d

Pass on a recommendation. Your companion learns from the dismissal.

spine refresh

Kicks off a fresh round of recommendations. New picks show up within a minute.

Shelves & building

Custom shelves are curated sub-collections inside your bookcase. You can build them by hand or ask your companion to assemble one from a prompt.

spine shelves [subcommand]

Manages custom shelves. Without a subcommand, lists every shelf you own. With a subcommand, creates, views, edits, or deletes one.

create <name> string Creates a new shelf. Accepts --desc.
view <name> string Lists the books on a shelf.
add <book> string Adds a book from your bookcase to a shelf. Requires --shelf <name>.
remove <book> string Removes a book from a shelf. Requires --shelf <name>.
delete <name> string Deletes a shelf. Books stay in your bookcase.

$ spine shelves
$ spine shelves create "Beach Reads" --desc "Summer 2026"
$ spine shelves view "Beach Reads"
$ spine shelves add "The Midnight Library" --shelf "Beach Reads"

spine shelves-from <name> <title...>

Creates a shelf and populates it with books by title in one go. Each title gets resolved against the catalog, added to your bookcase if needed, then placed on the new shelf. Reports what it found and what it couldn't.

$ spine shelves-from "Cozy Mysteries" \
    "The Body in the Library" \
    "A Murder Most Natural"

spine build <prompt>

Asks your companion to build a themed shelf from a natural-language prompt. Returns a shelf name and up to ten picks with reasoning for each.

$ spine build "cozy mysteries set in bookshops with female protagonists"

spine like <type> <target>

Likes or unlikes a shelf, custom list, or review. Toggles, so running it twice undoes the like.

type enum · required list, review, or shelf.
target string · required The name of the list or shelf, or the ID of the review.

$ spine like list "Beach Reads"

Follow other readers and see what they're shelving.

spine feed

Your friends' recent activity: reviews, books added, likes. Chronological.

spine follow <username>

Follow a Spine user by username (no @).

$ spine follow "sarah_reads"

spine notifications alias: notifs

Your 20 most recent notifications: likes, follows, new recommendations.

Admin

Key management and catalog housekeeping.

spine api-key

Generates a new API key and prints instructions for saving it to ~/.spine.json. Rotates the existing key if you have one.

spine report <title>

Reports a data issue with a book. Requires librarian status.

--type string · default: bad_data bad_cover, bad_data, wrong_author, or bad_shop_link.

$ spine report "the hobbit" --type bad_cover

spine pipeline

Prints the enrichment queue status: how many books are pending, done, or failed.