1.\" Man page for llm_aggregator
  2.TH LLM_AGGREGATOR 1 "22 April 2026" "1.0.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 \-\-feeds-file
  9\fIFILE\fR
 10.B \-\-prompt
 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
 43Feeds are fetched concurrently for optimal performance, with rate limiting
 44to avoid overwhelming feed servers.
 45.SH REQUIRED ARGUMENTS
 46.TP
 47.B \-\-feeds-file \fIFILE\fR
 48Path to a file containing RSS feed URLs, one per line.
 49.TP
 50.B \-\-prompt \fIPROMPT\fR
 51User prompt for summarisation or analysis. This is sent to the LLM along
 52with the article content.
 53.SH OPTIONS
 54.SS Feed Aggregation Options
 55.TP
 56.B \-\-max\-articles\-per\-feed \fIN\fR
 57Maximum number of articles to fetch from each feed.
 58.br
 59Default: 10
 60.TP
 61.B \-\-max\-days\-old \fIN\fR
 62Only include articles from the last N days. Set to 0 to include all articles
 63regardless of age.
 64.br
 65Default: 7
 66.TP
 67.B \-\-max\-total\-articles \fIN\fR
 68Maximum total number of articles to process across all feeds.
 69.br
 70Default: 20
 71.SS Content Filtering
 72.TP
 73.B \-\-include\-keywords \fILIST\fR
 74Comma\-separated list of keywords to include. Only articles containing at
 75least one of these keywords (case\-insensitive) will be processed.
 76.TP
 77.B \-\-exclude\-keywords \fILIST\fR
 78Comma\-separated list of keywords to exclude. Any article containing one of
 79these keywords (case\-insensitive) will be filtered out.
 80.SS LLM API Options
 81.TP
 82.B \-\-api\-key \fIKEY\fR
 83OpenAI\-compatible API key. Can also be set via the
 84.B LLM_AGGREGATOR_API_KEY
 85environment variable.
 86.TP
 87.B \-\-base\-url \fIURL\fR
 88API base URL for the LLM service.
 89.br
 90Default: https://api.deepseek.com
 91.TP
 92.B \-\-model \fIMODEL\fR
 93LLM model to use for summarisation.
 94.br
 95Default: deepseek-chat
 96.TP
 97.B \-\-max\-tokens \fIN\fR
 98Maximum number of tokens in the LLM response.
 99.br
100Default: 4000
101.TP
102.B \-\-temperature \fIVALUE\fR
103Sampling temperature for the LLM (0.0 to 1.0). Higher values produce more
104creative output, lower values produce more deterministic output.
105.br
106Default: 0.7
107.TP
108.B \-\-system\-prompt \fITEXT\fR
109Custom system prompt for the LLM. If not specified, a default prompt is used.
110.SS Output Options
111.TP
112.B \-\-output \fIFORMAT\fR
113Output format. Must be one of:
114.RS 12
115.TP 4
116.B text
117Plain text output (default)
118.TP
119.B markdown
120GitHub\-flavoured markdown output
121.TP
122.B json
123JSON output with structured data
124.RE
125.TP
126.B \-\-output\-file \fIFILE\fR
127Write output to FILE instead of stdout.
128.TP
129.B \-\-include\-articles
130Include the original articles in JSON output. Only applicable when
131.B \-\-output json
132is used.
133.SS Interface Options
134.TP
135.B \-\-tui
136Enable the TUI interface with a progress bar, live article counters, and
137elapsed time display. The TUI supports keyboard navigation (j/k, arrows,
138space, b, g/G) and mouse wheel scrolling.
139.TP
140.B \-v\fR,\fB \-\-verbose
141Enable verbose logging. Shows detailed progress information during execution.
142.SS General Options
143.TP
144.B \-\-version
145Show version information and exit.
146.TP
147.B \-h\fR,\fB \-\-help
148Show this help message and exit.
149.SH ENVIRONMENT VARIABLES
150All configuration options can be set via environment variables with the
151.B LLM_AGGREGATOR_
152prefix:
153.TP
154.B LLM_AGGREGATOR_API_KEY
155LLM API key (required if not provided via \-\-api\-key)
156.TP
157.B LLM_AGGREGATOR_BASE_URL
158API base URL (default: "https://api.deepseek.com")
159.TP
160.B LLM_AGGREGATOR_MODEL
161Model name (default: "deepseek-chat")
162.TP
163.B LLM_AGGREGATOR_MAX_TOKENS
164Maximum tokens in response (default: 4000)
165.TP
166.B LLM_AGGREGATOR_TEMPERATURE
167Sampling temperature (default: 0.7)
168.TP
169.B LLM_AGGREGATOR_SYSTEM_PROMPT
170Custom system prompt
171.TP
172.B LLM_AGGREGATOR_MAX_ARTICLES_PER_FEED
173Maximum articles per feed (default: 10)
174.TP
175.B LLM_AGGREGATOR_MAX_DAYS_OLD
176Maximum article age in days (default: 7)
177.TP
178.B LLM_AGGREGATOR_MAX_TOTAL_ARTICLES
179Maximum total articles (default: 20)
180.TP
181.B LLM_AGGREGATOR_INCLUDE_KEYWORDS
182Comma\-separated include keywords
183.TP
184.B LLM_AGGREGATOR_EXCLUDE_KEYWORDS
185Comma\-separated exclude keywords
186.TP
187.B LLM_AGGREGATOR_OUTPUT
188Output format (default: "text")
189.TP
190.B LLM_AGGREGATOR_OUTPUT_FILE
191Output file path
192.TP
193.B LLM_AGGREGATOR_INCLUDE_ARTICLES
194Include articles in JSON output (true/false)
195.SH CONFIGURATION FILE
196Configuration can also be provided via a TOML file at:
197.PP
198.RS 4
199~/.config/llm_aggregator/config.toml
200.RE
201.PP
202See
203.BR llm_aggregator (5)
204for details on the configuration file format.
205.PP
206The precedence order for configuration (highest to lowest) is:
207.RS 4
208.TP 2
2091.
210Command\-line arguments
211.TP 2
2122.
213Environment variables
214.TP 2
2153.
216Configuration file
217.TP 2
2184.
219Built\-in defaults
220.RE
221.SH EXAMPLES
222.SS Basic Usage
223.PP
224Summarise tech news from a list of feeds:
225.PP
226.RS 4
227.nf
228llm_aggregator \-\-feeds-file feeds.txt \\
229    \-\-prompt "What are the latest AI\-related trends in free software?"
230.fi
231.RE
232.SS Using TUI
233.PP
234Enable the TUI interface with a progress bar:
235.PP
236.RS 4
237.nf
238llm_aggregator \-\-feeds-file feeds.txt \-\-prompt "Summarise tech news" \-\-tui
239.fi
240.RE
241.SS JSON Output with Articles
242.PP
243Output to a JSON file with original articles included:
244.PP
245.RS 4
246.nf
247llm_aggregator \-\-feeds-file feeds.txt \-\-prompt "Analyse AI developments" \\
248    \-\-output json \-\-output-file analysis.json \-\-include\-articles
249.fi
250.RE
251.SS Filtering by Keywords
252.PP
253Only include articles about Linux or open source:
254.PP
255.RS 4
256.nf
257llm_aggregator \-\-feeds-file feeds.txt \-\-prompt "Linux news" \\
258    \-\-include\-keywords linux,opensource \-\-max\-days\-old 3
259.fi
260.RE
261.SS Custom Model and API Endpoint
262.PP
263Use a custom model with a higher token limit or local endpoint:
264.PP
265.RS 4
266.nf
267llm_aggregator \-\-feeds-file feeds.txt \-\-prompt "Code analysis" \\
268    \-\-model deepseek-reasoner \-\-max-tokens 8000
269
270llm_aggregator \-\-feeds-file feeds.txt \-\-prompt "Summarise news" \\
271    \-\-base-url "http://localhost:11434/v1" \-\-model llama3
272.fi
273.RE
274.SS Custom System Prompt
275.PP
276Provide a custom system prompt for different analysis styles:
277.PP
278.RS 4
279.nf
280llm_aggregator \-\-feeds-file feeds.txt \\
281    \-\-prompt "Identify security vulnerabilities" \\
282    \-\-system-prompt "You are a security expert. Focus on identifying \\
283potential vulnerabilities, data breaches, and security advisories."
284.fi
285.RE
286.SH FEEDS FILE FORMAT
287The feeds file should contain one RSS or Atom feed URL per line. Blank lines
288and lines starting with
289.B #
290are ignored as comments. Example:
291.PP
292.RS 4
293.nf
294# Technology news
295https://news.ycombinator.com/rss
296https://lwn.net/headlines/newrss
297
298# Programming
299https://opensource.com/feed
300https://www.phoronix.com/rss.php
301.fi
302.RE
303.SH DEPENDENCIES
304.B llm_aggregator
305uses the following Go libraries:
306.TP 2
307\(bu
308.BR gofeed
309\- RSS/Atom/JSON feed parser
310.TP 2
311\(bu
312.BR openai-go
313\- OpenAI API client
314.TP 2
315\(bu
316.BR bubbletea
317\- TUI framework
318.TP 2
319\(bu
320.BR lipgloss
321\- Terminal styling
322.TP 2
323\(bu
324.BR go-arg
325\- Argument parsing
326.TP 2
327\(bu
328.BR tiktoken-go
329\- Token counting
330.TP 2
331\(bu
332.BR viper
333\- Configuration management
334.TP 2
335\(bu
336.BR goquery
337\- HTML scraping
338.SH EXIT STATUS
339.TP
340.B 0
341Success
342.TP
343.B 1
344Error (invalid arguments, missing API key, API error, etc.)
345.SH FILES
346.TP
347.B ~/.config/llm_aggregator/config.toml
348Default location for TOML configuration file.
349.SH SEE ALSO
350.BR llm_aggregator (5)
351for configuration file documentation.
352.PP
353Project homepage: https://codeberg.org/maxwelljensen/llm_aggregator
354.SH AUTHOR
355Written by Maxwell Jensen.
356.SH REPORTING BUGS
357Report bugs at: https://codeberg.org/maxwelljensen/llm_aggregator/issues
358.SH COPYRIGHT
359Copyright \(co 2026 Maxwell Jensen.
360.br
361Licensed under the European Union Public Licence 1.2 (EUPL\-1.2).
362.br
363See
364.BR LICENCE.txt
365for full licence details.