Skip to main content
Logo

CLI

@bestblogs/cli — the official command-line wrapper around the OpenAPI.

What it is

@bestblogs/cli is the officially maintained CLI wrapper around the BestBlogs OpenAPI, written in TypeScript / Node.js.

It packages:

  • OpenAPI Key management (configure once, available everywhere)
  • Pagination, error retries, rate-limit backoff
  • Imperative commands for the common resource families

It fits scripts, agent integrations, and local workflow automation.

Install

# global install
npm i -g @bestblogs/cli

# verify
bestblogs --version

First-time setup

bestblogs auth login
# prompts for an OpenAPI Key (create one under Settings → OpenAPI)
# the key is stored encrypted in ~/.bestblogs/config.json

You can also use an env var: export BESTBLOGS_API_KEY=bb_live_xxx — the CLI prefers it over the stored config.

Common commands

Fetch today's brief

bestblogs brief today
bestblogs brief today --json > today.json

List curated content

bestblogs discover list --type article --time 1w --qualified
bestblogs discover list --type podcast --language en --limit 50

Get an item's body + summary

bestblogs read get art_123
bestblogs read get art_123 --summary key_points

Bookmark / highlight

bestblogs capture bookmark art_123 --folder inbox --tags inspiration,to-write
bestblogs capture highlight art_123 --text "..." --comment "..."

Ask the AI Reading Assistant

bestblogs copilot ask art_123 "What agent architecture does the author recommend?"

List your followed sources

bestblogs sources list --following

Use in scripts

The CLI prints tables by default; pass --json to pipe JSON straight into other tools:

bestblogs discover list --type article --time 24h --qualified --json \
  | jq '.data[] | {title, score, url}'

Integrate with an LLM / agent

The CLI is designed to be agent-friendly — every command takes --json, exit codes follow POSIX conventions, and token usage is written to stderr.

If you're building a local reading agent, the minimum loop:

  1. bestblogs brief today --json to get today's reading list
  2. For each item, bestblogs read get <id> --summary key_points
  3. Write back with bestblogs capture bookmark <id> --note "..."

Claude Code / Codex / Cursor users: just install Agent Skills (npx @bestblogs/skills install). The 5 skills already wrap this loop and trigger on natural-language asks.

Full schema and advanced usage in the GitHub README.

← Back to docs home