newsblur-cli

Engineering Community

Repo stars 7,469
License MIT
Author repo NewsBlur

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: Manage your NewsBlur from the terminal. Read feeds, search stories, save and share articles, train intelligence classifiers, dis…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “Setup”, “Readonly Mode”, “Output Formats”, “Commands”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name newsblur-cli directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “Setup / Readonly Mode / Output Formats” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read / write; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

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

Fluxly profile Author and license come from source; runtime, permissions, and network are Fluxly detections or estimates

Fluxly category: Engineering
Author-declared agents: No explicit declaration found; this is not inferred or tested compatibility
Static check: 94 / 100 · heuristic scan, not runtime safety proof
Author / version / license: @samuelclay · MIT
Fluxly token estimate: Lean
Fluxly setup estimate: Plug-and-play
External API key: No requirement detected
Detected OS requirements: Unspecified
Runtime requirements: Python >=3.11
Detected file/system behavior: Read-only
Write / modify
Detected network behavior: External requests
Install commands: None (reference only)

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview newsblur-cli.preview

# Scripting Examples

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

SKILL.md SKILL.md

# 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
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`:

```bash
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.

```bash
newsblur auth readonly --on
```

Check current readonly status:

```bash
newsblur auth readonly
```

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

```bash
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:

```bash
newsblur stories list
```

Filter by folder or limit results:

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

Full-text search across your archive:

```bash
newsblur stories search "machine learning"
```

View saved/starred stories, optionally filtered by tag:

```bash
newsblur stories saved
newsblur stories saved --tag research
```

…

Evidence boundary and execution chain

Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.

sections -> Setup → Readonly Mode → Output Formats → Commands → Stories → Daily Briefing
terms    -> The NewsBlur CLI (newsblur-cli) gives you full access to your NewsBlur account from the terminal. · auth login opens a browser for OAuth authorization. · The CLI has a readonly mode that blocks all write operations (saving, sharing, training, subscribing, marking as read). · Disabling readonly logs you out and requires browser re-authentication. · If you are operating in readonly mode, all write commands will fail with an error.
files/cmd -> newsblur-cli · auth login · ~/.config/newsblur/ · --server · NEWSBLURSERVER · --json · --raw
body sha256 -> 152f4f4d0299