newsblur-cli

name	newsblur-cli
description	Manage your NewsBlur from the terminal. Read feeds, search stories, save and share articles, train intelligence classifiers, discover new feeds, and automate workflows with the NewsBlur CLI. Use when the user wants to interact with their NewsBlur account, check feeds, manage subscriptions, or build scripts around their news reading.

NewsBlur CLI

The NewsBlur CLI (newsblur-cli) gives you full access to your NewsBlur account from the terminal. Install it and authenticate before running any commands.

Setup

uv pip install newsblur-cli
newsblur auth login

auth login opens a browser for OAuth authorization. The token is stored at ~/.config/newsblur/.

For self-hosted instances, pass --server or set NEWSBLUR_SERVER:

newsblur --server https://my-newsblur.example.com auth login

Readonly Mode

The CLI has a readonly mode that blocks all write operations (saving, sharing, training, subscribing, marking as read). Useful when handing the CLI to an AI agent.

newsblur auth readonly --on

Check current readonly status:

newsblur auth readonly

Disabling readonly logs you out and requires browser re-authentication. An AI agent cannot silently toggle this off.

newsblur auth readonly --off
# "You have been logged out and must re-authenticate."
newsblur auth login

If you are operating in readonly mode, all write commands will fail with an error. Read commands work normally.

Output Formats

Every command supports these flags:

• --json — structured JSON output, pipe to jq
• --raw — unformatted plain text
• Default — human-readable formatted output

Commands

Stories

List unread stories across all feeds:

newsblur stories list

Filter by folder or limit results:

newsblur stories list --folder Tech --limit 5

Full-text search across your archive:

newsblur stories search "machine learning"

View saved/starred stories, optionally filtered by tag:

newsblur stories saved
newsblur stories saved --tag research

Browse stories from rarely-publishing feeds (easy to miss in a busy river):

newsblur stories infrequent

Fetch the original full article text from the source:

newsblur stories original <story_hash>

View stories you've already read:

newsblur stories read

Daily Briefing

Get an AI-curated briefing with top stories, infrequent site gems, and long reads:

newsblur briefing
newsblur briefing --limit 1
newsblur briefing --json

Feeds and Folders

List all subscriptions:

newsblur feeds list

View the folder tree with unread counts:

newsblur feeds folders

Get detailed info about a specific feed:

newsblur feeds info <feed_id>

Subscribe to a new feed:

newsblur feeds add https://example.com/feed.xml
newsblur feeds add https://blog.com -f Tech

Unsubscribe from a feed:

newsblur feeds remove <feed_id>

Move a feed between folders or rename it:

newsblur feeds organize move_feed --feed-id 42 --from News --to Tech

Story Actions

Save a story with tags:

newsblur save <story_hash> --tag ai --tag research

Remove a story from saved:

newsblur unsave <story_hash>

Mark stories as read by feed, folder, or specific story hashes:

newsblur read --feed 42
newsblur read --folder Tech
newsblur read 123:abc 456:def

Share a story to your Blurblog:

newsblur share <story_hash> --comment "Worth reading"

Intelligence Training

View your trained classifiers for a feed:

newsblur train show --feed 42

Train a like on an author, tag, title, or feed:

newsblur train like --feed 42 --author "Ben Thompson"
newsblur train like --feed 42 --tag analysis
newsblur train like --feed 42 --title "quarterly earnings"

Train a dislike:

newsblur train dislike --feed 42 --tag sponsored
newsblur train dislike --feed 42 --author "Guest Post"

Feed Discovery

Search for new feeds by topic:

newsblur discover search "machine learning"

Find feeds similar to one you already follow:

newsblur discover similar --feed 42

Browse trending feeds:

newsblur discover trending

Notifications

Manage per-feed notification settings:

newsblur notifications --feed 42

Account

View your account info and subscription status:

newsblur account

Scripting Examples

Pipe story titles to the terminal:

newsblur stories list --json | jq -r '.items[] | "\(.title) - \(.feed_title)"'

Extract briefing summaries:

newsblur briefing --json | jq '.items[0].section_summaries'

Save all unread stories from a folder with a tag:

for hash in $(newsblur stories list --folder Research --json | jq -r '.items[].story_hash'); do
  newsblur save "$hash" --tag to-review
done

Export your feed list:

newsblur feeds list --json | jq -r '.items[] | "\(.feed_title),\(.feed_address)"'

Requirements

• Python 3.11+
• Premium Archive ($99/year) or Premium Pro ($29/month) subscription
• OAuth authentication via browser