1.\" Man page for llm_aggregator
  2.TH LLM_AGGREGATOR 1 "26 April 2026" "0.12.0" "User Commands"
  3.SH NAME
  4llm_aggregator \- aggregate RSS feeds and summarise them with LLMs
  5.SH SYNOPSIS
  6.B llm_aggregator
  7[\fIOPTIONS\fR]
  8.B \-f
  9\fIFILE\fR
 10.B \-p
 11\fIPROMPT\fR
 12.SH DESCRIPTION
 13.B llm_aggregator
 14is a command\-line utility that fetches articles from multiple RSS feeds,
 15filters and processes the content, and sends it to an LLM through an
 16OpenAI\-compatible API to generate a concise summary or analysis. It is
 17designed for keeping up with news and articles from your favourite sources
 18without having to read dozens or hundreds of individual posts.
 19.PP
 20The tool performs the following steps:
 21.TP 2
 22\(bu
 23Parse command\-line arguments
 24.TP 2
 25\(bu
 26Read the feeds file (plain text file containing one RSS/Atom feed URL per line)
 27.TP 2
 28\(bu
 29Fetch and parse feeds concurrently (supports RSS, Atom, and JSON Feed formats)
 30.TP 2
 31\(bu
 32Extract article content (title, link, publication date, author, description)
 33.TP 2
 34\(bu
 35Filter and sort articles by age and keywords
 36.TP 2
 37\(bu
 38Prepare the prompt with selected articles and send to the LLM
 39.TP 2
 40\(bu
 41Format and output the result in the chosen format (text, markdown, or JSON)
 42.PP
 43Output is styled with ANSI colours for better readability, but this software
 44respects the
 45.B NO_COLOR
 46environment variable (see https://no-color.org/).
 47.PP
 48Feeds are fetched concurrently for optimal performance, with rate limiting
 49to avoid overwhelming feed servers.
 50.SH REQUIRED ARGUMENTS
 51.TP
 52.B \-f\fR,\fB -f \fIFILE\fR
 53Path to a file containing RSS feed URLs, one per line.
 54.TP
 55.B \-p\fR,\fB -p \fIPROMPT\fR
 56User prompt for summarisation or analysis. This is sent to the LLM along
 57with the article content.
 58.SH OPTIONS
 59.SS Feed Aggregation Options
 60.TP
 61.B \-n\fR,\fB \-\-max\-articles\-per\-feed \fIN\fR
 62Maximum number of articles to fetch from each feed.
 63.br
 64Default: 10
 65.TP
 66.B \-d\fR,\fB \-\-max\-days\-old \fIN\fR
 67Only include articles from the last N days. Set to 0 to include all articles
 68regardless of age.
 69.br
 70Default: 7
 71.TP
 72.B \-\-max\-total\-articles \fIN\fR
 73Maximum total number of articles to process across all feeds.
 74.br
 75Default: 20
 76.SS Content Filtering
 77.TP
 78.B \-i\fR,\fB \-\-include\-keywords \fILIST\fR
 79Comma\-separated list of keywords to include. Only articles containing at
 80least one of these keywords (case\-insensitive) will be processed.
 81.TP
 82.B \-e\fR,\fB \-\-exclude\-keywords \fILIST\fR
 83Comma\-separated list of keywords to exclude. Any article containing one of
 84these keywords (case\-insensitive) will be filtered out.
 85.SS LLM API Options
 86.TP
 87.B \-\-api\-key \fIKEY\fR
 88OpenAI\-compatible API key. Can also be set via the
 89.B LLM_AGGREGATOR_API_KEY
 90environment variable.
 91.TP
 92.B \-\-base\-url \fIURL\fR
 93API base URL for the LLM service.
 94.br
 95Default: https://api.deepseek.com
 96.TP
 97.B \-m\fR,\fB -m \fIMODEL\fR
 98LLM model to use for summarisation.
 99.br
100Default: deepseek-chat
101.TP
102.B \-\-max\-tokens \fIN\fR
103Maximum number of tokens in the LLM response.
104.br
105Default: 4000
106.TP
107.B \-\-temperature \fIVALUE\fR
108Sampling temperature for the LLM (0.0 to 1.0). Higher values produce more
109creative output, lower values produce more deterministic output.
110.br
111Default: 0.7
112.TP
113.B \-\-system\-prompt \fITEXT\fR
114Custom system prompt for the LLM. If not specified, a default prompt is used.
115.SS Output Options
116.TP
117.B \-P\fR,\fB \-\-plain
118Output only the raw LLM response without any formatting or metadata. When
119active,
120.B -o\fR/
121.B \-\-output
122has no effect. Useful for piping or post-processing.
123.TP
124.B \-o\fR,\fB -o \fIFORMAT\fR
125Output format. Must be one of:
126.RS 12
127.TP 4
128.B text
129Plain text output (default)
130.TP
131.B markdown
132GitHub\-flavoured markdown output
133.TP
134.B json
135JSON output with structured data
136.RE
137.TP
138.B -o\-file \fIFILE\fR
139Write output to FILE instead of stdout.
140.TP
141.B \-\-include\-articles
142Include the original articles in JSON output. Only applicable when
143.B -o json
144is used.
145.TP
146.B \-P\fR,\fB \-\-plain
147Output only the raw LLM response without any formatting or metadata. When
148active,
149.B -o\fR/
150.B \-\-output
151has no effect. Useful for piping or post-processing.
152.SS Interface Options
153.TP
154.B \-D\fR,\fB \-\-dry\-run
155Validate configuration and preview what would happen without making any LLM
156API calls. Useful for:
157.RS 4
158.TP 2
159\(bu
160Validating feeds file and configuration
161.TP 2
162\(bu
163Checking article counts and filtering results
164.TP 2
165\(bu
166Estimating token usage before running
167.TP 2
168\(bu
169Testing network connectivity to feeds
170.RE
171.TP
172.B \-t\fR,\fB -t
173Enable the TUI interface with a progress bar, live article counters, and
174elapsed time display. The TUI supports keyboard navigation (j/k, arrows,
175space, b, g/G) and mouse wheel scrolling.
176.TP
177.B \-v\fR,\fB \-\-verbose
178Enable verbose logging. Shows detailed progress information during execution.
179.SS General Options
180.TP
181.B \-\-version
182Show version information and exit.
183.TP
184.B \-h\fR,\fB \-\-help
185Show this help message and exit.
186.SH ENVIRONMENT VARIABLES
187All configuration options can be set via environment variables with the
188.B LLM_AGGREGATOR_
189prefix:
190.TP
191.B LLM_AGGREGATOR_API_KEY
192LLM API key (required if not provided via \-\-api\-key)
193.TP
194.B LLM_AGGREGATOR_BASE_URL
195API base URL (default: "https://api.deepseek.com")
196.TP
197.B LLM_AGGREGATOR_MODEL
198Model name (default: "deepseek-chat")
199.TP
200.B LLM_AGGREGATOR_MAX_TOKENS
201Maximum tokens in response (default: 4000)
202.TP
203.B LLM_AGGREGATOR_TEMPERATURE
204Sampling temperature (default: 0.7)
205.TP
206.B LLM_AGGREGATOR_SYSTEM_PROMPT
207Custom system prompt
208.TP
209.B LLM_AGGREGATOR_MAX_ARTICLES_PER_FEED
210Maximum articles per feed (default: 10)
211.TP
212.B LLM_AGGREGATOR_MAX_DAYS_OLD
213Maximum article age in days (default: 7)
214.TP
215.B LLM_AGGREGATOR_MAX_TOTAL_ARTICLES
216Maximum total articles (default: 20)
217.TP
218.B LLM_AGGREGATOR_INCLUDE_KEYWORDS
219Comma\-separated include keywords
220.TP
221.B LLM_AGGREGATOR_EXCLUDE_KEYWORDS
222Comma\-separated exclude keywords
223.TP
224.B LLM_AGGREGATOR_OUTPUT
225Output format (default: "text")
226.TP
227.B LLM_AGGREGATOR_OUTPUT_FILE
228Output file path
229.TP
230.B LLM_AGGREGATOR_INCLUDE_ARTICLES
231Include articles in JSON output (true/false)
232.TP
233.B LLM_AGGREGATOR_PLAIN
234Plain output without metadata (true/false)
235.SH CONFIGURATION FILE
236Configuration can also be provided via a TOML file at:
237.PP
238.RS 4
239~/.config/llm_aggregator/config.toml
240.RE
241.PP
242See
243.BR llm_aggregator (5)
244for details on the configuration file format.
245.PP
246The precedence order for configuration (highest to lowest) is:
247.RS 4
248.TP 2
2491.
250Command\-line arguments
251.TP 2
2522.
253Environment variables
254.TP 2
2553.
256Configuration file
257.TP 2
2584.
259Built\-in defaults
260.RE
261.SH EXAMPLES
262.SS Basic Usage
263.PP
264Summarise tech news from a list of feeds:
265.PP
266.RS 4
267.nf
268llm_aggregator -f feeds.txt \\
269    -p "What are the latest AI\-related trends in free software?"
270.fi
271.RE
272.SS Validating Configuration (Dry Run)
273.PP
274Validate configuration and preview articles before making any LLM API calls:
275.PP
276.RS 4
277.nf
278llm_aggregator -f feeds.txt -p "Summarise news" -D
279.fi
280.RE
281.PP
282This shows article counts, filtering statistics, token estimates, and the
283prompt that would be sent. No API key is required for dry-run mode.
284.SS Using TUI
285.PP
286Enable the TUI interface with a progress bar:
287.PP
288.RS 4
289.nf
290llm_aggregator -f feeds.txt -p "Summarise tech news" -t
291.fi
292.RE
293.SS JSON Output with Articles
294.PP
295Output to a JSON file with original articles included:
296.PP
297.RS 4
298.nf
299llm_aggregator -f feeds.txt -p "Analyse AI developments" \\
300    -o json -o-file analysis.json \-\-include\-articles
301.fi
302.RE
303.SS Filtering by Keywords
304.PP
305Only include articles about Linux or open source:
306.PP
307.RS 4
308.nf
309llm_aggregator -f feeds.txt -p "Linux news" \\
310    \-\-include\-keywords linux,opensource \-\-max\-days\-old 3
311.fi
312.RE
313.SS Custom Model and API Endpoint
314.PP
315Use a custom model with a higher token limit or local endpoint:
316.PP
317.RS 4
318.nf
319llm_aggregator -f feeds.txt -p "Code analysis" \\
320    -m deepseek-reasoner \-\-max-tokens 8000
321
322llm_aggregator -f feeds.txt -p "Summarise news" \\
323    \-\-base-url "http://localhost:11434/v1" -m llama3
324.fi
325.RE
326.SS Custom System Prompt
327.PP
328Provide a custom system prompt for different analysis styles:
329.PP
330.RS 4
331.nf
332llm_aggregator -f feeds.txt \\
333    -p "Identify security vulnerabilities" \\
334    \-\-system-prompt "You are a security expert. Focus on identifying \\
335potential vulnerabilities, data breaches, and security advisories."
336.fi
337.RE
338.SH FEEDS FILE FORMAT
339The feeds file should contain one RSS or Atom feed URL per line. Blank lines
340and lines starting with
341.B #
342are ignored as comments. Example:
343.PP
344.RS 4
345.nf
346# Technology news
347https://news.ycombinator.com/rss
348https://lwn.net/headlines/newrss
349
350# Programming
351https://opensource.com/feed
352https://www.phoronix.com/rss.php
353.fi
354.RE
355.SH DEPENDENCIES
356.B llm_aggregator
357uses the following Go libraries:
358.TP 2
359\(bu
360.BR gofeed
361\- RSS/Atom/JSON feed parser
362.TP 2
363\(bu
364.BR openai-go
365\- OpenAI API client
366.TP 2
367\(bu
368.BR bubbletea
369\- TUI framework
370.TP 2
371\(bu
372.BR lipgloss
373\- Terminal styling
374.TP 2
375\(bu
376.BR go-arg
377\- Argument parsing
378.TP 2
379\(bu
380.BR tiktoken-go
381\- Token counting
382.TP 2
383\(bu
384.BR viper
385\- Configuration management
386.TP 2
387\(bu
388.BR goquery
389\- HTML scraping
390.SH EXIT STATUS
391.TP
392.B 0
393Success
394.TP
395.B 1
396Error (invalid arguments, missing API key, API error, etc.)
397.SH FILES
398.TP
399.B ~/.config/llm_aggregator/config.toml
400Default location for TOML configuration file.
401.SH SEE ALSO
402.BR llm_aggregator (5)
403for configuration file documentation.
404.PP
405Project homepage: https://codeberg.org/maxwelljensen/llm_aggregator
406.SH AUTHOR
407Written by Maxwell Jensen.
408.SH REPORTING BUGS
409Report bugs at: https://codeberg.org/maxwelljensen/llm_aggregator/issues
410.SH COPYRIGHT
411Copyright \(co 2026 Maxwell Jensen.
412.br
413Licensed under the European Union Public Licence 1.2 (EUPL\-1.2).
414.br
415See
416.BR LICENCE.txt
417for full licence details.