Command-line (CLI)

brightbean is a single-binary CLI built on the TypeScript SDK. Every endpoint is reachable from your shell, with JSON-by-default output for jq and pipelines, plus a --pretty mode for humans.

• Package: @brightbean/cli on npm
• Source: github.com/JanSchm/social-intelligence-app/tree/main/sdks/cli
• Requires Node 18+

Install

npm install -g @brightbean/cli

Authentication

export BRIGHTBEAN_API_KEY=bb_...
brightbean auth status           # offline check (no network)
brightbean auth status --online  # validates against GET /v1/me/

Or keep multiple profiles in ~/.brightbean/config:

default = work

[work]
api_key = bb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

[personal]
api_key = bb_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

Then brightbean --profile personal score --title "...".

Global flags

By default every command writes JSON to stdout. Pipe to jq, capture into shell variables, redirect to files — standard tools. --pretty switches to a human layout (currently implemented for score and usage; other commands always emit JSON).

Commands

brightbean score

brightbean score --title "10 Tips to Boost Your Coding Productivity"
brightbean score --thumb thumb.jpg --title "..."
brightbean score --thumb -                    # read thumbnail bytes from stdin
echo "title text" | brightbean score          # piped title
brightbean score --title "..." --pretty

Score a packaging (title and/or thumbnail). At least one input is required. Cost: 1 / 2 / 3 credits depending on mode.

brightbean score-video-hook

brightbean score-video-hook --url 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
brightbean score-video-hook --url 'https://youtu.be/dQw4w9WgXcQ' --pretty

Hook quality on the first ~6 s of a video. Cost: 10 credits.

brightbean benchmark channel

brightbean benchmark channel --url 'https://www.youtube.com/@MarquesBrownlee'
brightbean benchmark channel --url '@MarquesBrownlee' | jq '.niche.match_strength'

Channel vs. niche. Cost: 5 credits.

brightbean benchmark video

brightbean benchmark video --url 'https://www.youtube.com/watch?v=dQw4w9WgXcQ' \
  | jq '.video.engagement_percentiles'

Single video vs. niche. Cost: 3 credits.

brightbean niches

brightbean niches | jq '.[].slug' | head -20

List all catalogued niche slugs. Cost: 1 credit.

brightbean content-gaps

brightbean content-gaps --niche tech-tutorials \
  --gap-type underserved \
  --gap-type stale \
  --limit 10 \
  --min-score 70

Ranked content opportunities for a niche. Valid --gap-type values: underserved, stale, competitive. Default is underserved + stale; competitive is opt-in. Pass --gap-type multiple times to combine. Cost: 5 credits.

brightbean usage

brightbean usage              # JSON
brightbean usage --pretty     # human-readable balance + recent calls

Live credit balance and recent activity. Free.

brightbean me

brightbean me

Account info and plan details. Free.

brightbean auth status

brightbean auth status               # offline: prints which key would be used
brightbean auth status --online      # validates against the API

Sanity-check your auth configuration. Free when online.

Piping examples

# Score 50 titles from a CSV
cut -d, -f1 titles.csv | while read title; do
  brightbean score --title "$title" --json-errors \
    | jq -c '{title: "'$title'", score, percentile, niche_slug}'
done > scored.ndjson

# Re-score the lowest-percentile titles with a thumbnail experiment
jq -r 'select(.percentile < 50) | .title' scored.ndjson | while read title; do
  brightbean score --title "$title" --thumb new-thumb.jpg | jq '.percentile'
done

Exit codes