FreshRSS Tips: Turn Search Into a Rules Engine

It is easy to treat the FreshRSS search box like every other search box: type a word, scan the results, move on.

That misses most of what it can do. The box accepts a small query language, and FreshRSS builds its best automation on top of it. The same expression that finds articles can run automatically on everything a feed receives. Save it and you have a virtual feed; share it and another application can subscribe to the result as RSS.

1. The Operators, In One Place

Keep this section handy; everything else builds on it.

There is no space between an operator and its value. intitle:kubernetes works. intitle: kubernetes does not.

Multi-word values go in single or double quotes: author:'Bruce Schneier'.

And the glue that holds them together:

A couple of things that will bite you eventually:

• OR has to be uppercase. Lowercase or is treated as a plain search word.
• A literal parenthesis has to be escaped as \( and \), or wrapped in quotes like "a (b)".
• Searches run against the HTML of the article, but FreshRSS encodes <, & and " for you, so you can search for 'A & B' without escaping anything. The exception is regex, where nothing is encoded, which is exactly what lets you search for markup.

Finding the numeric IDs

f: and c: want numbers, and FreshRSS does not show them prominently. The quickest way is to click a feed or category in the sidebar and read the ID out of the address bar. There is also a small extension called ShowFeedID that puts them in the interface permanently, which is worth installing if you write a lot of these.

2. Dates Are Better Than You Think

ISO 8601 intervals, which sound scarier than they are.

The date operators accept fixed dates, ranges, and durations relative to right now. That last option is usually the most useful.

A duration starts with P, and T separates the date part from the time part. So P3D is three days, PT5H is five hours, and P1DT1H is one day and one hour.

There is one syntax that looks like it should work and does not: date:/P1M is not supported. Use the negation form !date:P1M instead.

3. Use Narrow Regular Expressions

Anchor patterns carefully and test them against real feed data.

Regular expressions go between forward slashes, and they work on intitle:, author:, inurl: and #tag. Add i for case-insensitive, m for multiline.

One detail explains why a regex can behave differently as a filter than it did in search:

Three habits that keep regex filters sane:

Anchor them. An unanchored pattern matches anywhere in the field. intitle:/news/ will happily match “Renews”, “Newsletter” and “Bad news.” Use \b for word boundaries. FreshRSS translates \b for PostgreSQL automatically, so it is safe to use everywhere.

Escape your slashes. A literal / inside the pattern has to be written \/. This bites people writing URL patterns constantly.

Reach for plain operators first. intitle:sponsored OR intitle:'paid post' is easier to read, easier to fix six months from now, and usually faster than one clever regex that does the same job.

4. Kill the Noise Before You See It

Filter actions: the single highest-value feature in FreshRSS.

A filter action is a search expression that runs automatically against articles as they arrive.

Open any feed’s settings from Subscription management and you will find a box labeled Filter actions. Write one expression per line. FreshRSS combines the lines with OR, so any matching line triggers the action. Each line remains an independent rule instead of becoming part of one large expression.

There is a Preview filters on existing articles link right below the box. Use it before saving a rule, especially if you plan to apply it to existing articles. The preview uses database search, so a complex regular expression can match differently when the live filter runs through PHP.

Here are the rules that earn their keep.

5. Now Flip It Around

So far, we’ve hidden articles you don’t want. The same filters can star the ones you do.

FreshRSS puts its three filter actions in different parts of the interface:

That table is the answer to “why can’t I set up auto-favorite on a single feed?” You scope it yourself, by putting f: or c: into the expression.

6. Labels Are Workflow States, Not Decoration

A short, consistent list is easier to maintain.

It is tempting to use labels as topics, much like browser bookmark folders. Categories and feed tags already handle topics. Labels are more useful as states that show where an article is in your process.

A practical starting set:

You can then combine those states in saved queries.

7. Saved Queries Are Virtual Feeds

FreshRSS calls them user queries. They are considerably more than bookmarks.

Once you have an expression you like, save it. Run the search, open the dropdown next to the state buttons, and bookmark it. It now appears in that dropdown permanently.

FreshRSS stores the query, not a frozen set of results. It runs the search again every time you open it, so today’s articles naturally differ from next month’s. Think of it as a feed assembled from your other feeds on demand.

Queries can reference other queries

Saved queries can also call one another, which is where the language becomes much easier to maintain.

You can refer to a saved query from inside another query, by name with search: or by ID with S:. FreshRSS substitutes the referenced query’s expression into the new one before it runs.

So build small, named pieces and combine them:

Fix your definition of “noise” in one place and every query that references it improves with it. Think of saved-query references as small reusable functions; they are much easier to maintain than six near-identical expressions.

8. Publish a Query as a Real RSS Feed

Turn a private search into an input another tool can consume.

A saved query can be exposed at its own URL, in HTML, RSS, or OPML.

Use this when another tool should receive only a filtered subset of your subscriptions:

1. FreshRSS fetches, deduplicates, filters, and labels the source feeds.
2. A saved query selects the articles you want, such as urgent security posts from the last seven days.
3. The published RSS URL sends those results to Slack, n8n, a static site, or another reader.

To turn it on:

Sharing a User Query

Two prerequisites and one checkbox.

9. Two Settings That Prevent a Lot of Duplicates

Use built-in duplicate detection before writing another filter.

If you follow more than a handful of news sources, you have the syndication problem: one wire story, eleven outlets, eleven entries in your reader.

Configuration → Reading has options for exactly this, under Mark an article as read…:

• if an identical title already exists in the top n newest articles of the feed: catches a publisher republishing its own post
• if an identical title already exists in the top n newest articles of the category: useful when several sources cover the same news. Put those sources in one category, set n to something like 100, and later copies of the same headline arrive already read
• if an identical GUID already exists in the top n newest articles of the category: handles feeds that share identifiers, as syndication partners sometimes do

Two neighboring settings help keep the unread count under control:

• when it is no longer in the upstream news feed: useful for job boards and status pages, where a missing entry is no longer relevant
• Max number of articles to keep unread: sets a hard ceiling. Once you exceed it, FreshRSS marks the oldest unread articles as read automatically, preventing a huge backlog after time away

10. Before You Trust a Rule, Test It

A filter that marks the wrong thing as read is worse than no filter at all, because the mistake is almost invisible.

Three checks, in order of effort:

Run it in the search box first. Every filter expression is a valid search expression. Paste it in, look at what comes back, and pay attention to what you did not expect.

Use the preview link. The Preview filters on existing articles link under the Filter actions box searches what is already in your database and shows the matches in a new window. It is a useful check, though complex regex can behave differently in the live filter’s PHP engine.

Use the global view for counts. FreshRSS’s global view shows how many articles per feed match a search expression. If one feed matches ninety percent of its own articles, the rule is probably too broad.

Then give it a week and check the results. Search for the expression, sort by date, and confirm the recent matches are all things you meant to filter.