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

bash
1uv pip install newsblur-cli
2newsblur 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:

bash
1newsblur --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.

bash
1newsblur auth readonly --on

Check current readonly status:

bash
1newsblur auth readonly

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

bash
1newsblur auth readonly --off
2# "You have been logged out and must re-authenticate."
3newsblur 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:

bash
1newsblur stories list

Filter by folder or limit results:

bash
1newsblur stories list --folder Tech --limit 5

Full-text search across your archive:

bash
1newsblur stories search "machine learning"

View saved/starred stories, optionally filtered by tag:

bash
1newsblur stories saved
2newsblur stories saved --tag research

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

bash
1newsblur stories infrequent

Fetch the original full article text from the source:

bash
1newsblur stories original <story_hash>

View stories you've already read:

bash
1newsblur stories read

Daily Briefing

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

bash
1newsblur briefing
2newsblur briefing --limit 1
3newsblur briefing --json

Feeds and Folders

List all subscriptions:

bash
1newsblur feeds list

View the folder tree with unread counts:

bash
1newsblur feeds folders

Get detailed info about a specific feed:

bash
1newsblur feeds info <feed_id>

Subscribe to a new feed:

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

Unsubscribe from a feed:

bash
1newsblur feeds remove <feed_id>

Move a feed between folders or rename it:

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

Story Actions

Save a story with tags:

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

Remove a story from saved:

bash
1newsblur unsave <story_hash>

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

bash
1newsblur read --feed 42
2newsblur read --folder Tech
3newsblur read 123:abc 456:def

Share a story to your Blurblog:

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

Intelligence Training

View your trained classifiers for a feed:

bash
1newsblur train show --feed 42

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

bash
1newsblur train like --feed 42 --author "Ben Thompson"
2newsblur train like --feed 42 --tag analysis
3newsblur train like --feed 42 --title "quarterly earnings"

Train a dislike:

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

Feed Discovery

Search for new feeds by topic:

bash
1newsblur discover search "machine learning"

Find feeds similar to one you already follow:

bash
1newsblur discover similar --feed 42

Browse trending feeds:

bash
1newsblur discover trending

Notifications

Manage per-feed notification settings:

bash
1newsblur notifications --feed 42

Account

View your account info and subscription status:

bash
1newsblur account

Scripting Examples

Pipe story titles to the terminal:

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

Extract briefing summaries:

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

Save all unread stories from a folder with a tag:

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

Export your feed list:

bash
1newsblur 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