biblioscan-cli

README

biblioscan-cli

Command-line client for the BiblioScan API — the book-scouting platform for used-book resellers. Scan shelves or barcodes, get prices, sales rank and buy signals, manage your buy lists and inventory, straight from your terminal or your scripts.

This CLI is a thin, dependency-light wrapper over the public API: every command maps to a documented endpoint, so it doubles as living documentation for your own integrations.

Install

From releases — grab a binary for Linux/macOS/Windows (amd64/arm64) from Releases.

With Go (1.25+):

go install github.com/biblioscan/biblioscan-cli@latest

go install names the binary biblioscan-cli — rename it (mv $(go env GOPATH)/bin/biblioscan-cli $(go env GOPATH)/bin/biblioscan) or grab a release binary, which is already named biblioscan.

Authentication

Create an API key in the BiblioScan app (Settings → API keys), then either:

biblioscan config set-key bsk_xxxxxxxxxxxxxxxx   # stored in your user config dir (0600)
# or
export BIBLIOSCAN_API_KEY=bsk_xxxxxxxxxxxxxxxx

Keys are sent raw in the Authorization header (no Bearer prefix). They can call every data route but can never change your password, delete your account or manage API keys — see the API docs.

Quickstart

biblioscan me                                    # profile + remaining credits
biblioscan barcode scan 9782070612758 --lang fr  # analyze one book by ISBN (1 credit)
biblioscan barcode scan 2070612759 --lang fr     # …or by ASIN
biblioscan stock export --format csv > stock.csv

Scanning a book

barcode scan is the command you'll reach for most. Give it an ISBN, EAN or ASIN and it returns the full pricing and demand picture for that book on the marketplace you target.

biblioscan barcode scan 9782070612758 --lang fr

FIELD                 VALUE
Title                 LE PETIT PRINCE
Authors               Saint-Exupery, Antoine de
ISBN                  9782070612758
ASIN                  2070612759
Current used price    6.50
Mean used price       5.61
Lowest price now      6.50
Amazon price          6.50
Sales rank            56
Used offers           56
Total offers          31
Sales last 12 months  -
Sales last 3 months   17
Cover                 https://images-na.ssl-images-amazon.com/images/I/710wth0vXZL.jpg
Data updated          2026-08-02T12:09:44.482Z

Amounts are in the marketplace's own currency and a - means the API has no value for that field. Either identifier gets you the same record — scanning 9782070612758 or its ASIN 2070612759 returns the row above in both cases.

--lang is required — it selects the Amazon marketplace the prices, rank and sales are read from, so the same book scanned with --lang fr and --lang us gives different numbers. Accepted values: us, fr, de, gb, jp, ca, cn, it, es.

Each scan costs 1 barcode credit and asks for confirmation first. Pass --yes in scripts:

biblioscan barcode scan 9782070612758 --lang fr --yes

The analysis runs server-side, so the command polls until the data is fresh (progress dots go to stderr, and it gives up after 5 minutes). To fire and forget instead, use --no-wait — you get a scan id back and pick the result up later, for free and with no polling:

id=$(biblioscan barcode scan 9782070612758 --lang fr --yes --no-wait --json | jq -r .barcodeScanId)
biblioscan barcode show "$id"

Add --json to get the raw API response for scripting:

biblioscan barcode scan 9782070612758 --lang fr --yes --json \
  | jq '.metadata.sources.keepa | {title, used: .currentusedprice, rank}'

Past scans stay available for free — barcode show <id> re-reads one, barcode list paginates your history:

biblioscan barcode list --page 2

If a refresh fails but cached data exists, the scan still prints and a warning goes to stderr telling you the numbers may be stale.

Commands

Group	What it does
barcode scan/show/list	Analyze a book by ISBN, EAN or ASIN — prices, rank, sales. See Scanning a book
me, referrals	Profile, credits, referral stats
scans create/list/show/…	Shelf scans: upload photos, every spine identified and priced
booklist …	Buy lists: collect the books worth buying across scans
stock …	Inventory: add, update, export (CSV/JSON) your physical stock
amazon …	Amazon Seller: listing restrictions, sales history, FBA stock
billing …	Payments and subscriptions (read-only)
config set-key/path	Local configuration
lookup <ASIN>	Metadata-only lookup, ASIN exclusively

Every read/query command supports --json to print the raw API response — pipe it to jq for scripting:

biblioscan stock list --json | jq '.[] | select(.salePrice == null) | .title'

Credits

barcode scan (1 barcode credit per call) and scans create (shelf-scan credits per image) consume credits from your plan and ask for confirmation first — pass --yes in scripts. Everything else is free. Both accept --no-wait to return immediately instead of polling.

Development

go build -o biblioscan .   # build
go test ./...              # tests (offline — httptest only)

Releases are cut by tagging v* — GoReleaser builds and publishes the binaries.

License

MIT