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