1.\" Man page for llm_aggregator
  2.TH LLM_AGGREGATOR 1 "23 April 2026" "0.9.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 \-o\fR,\fB -o \fIFORMAT\fR
118Output format. Must be one of:
119.RS 12
120.TP 4
121.B text
122Plain text output (default)
123.TP
124.B markdown
125GitHub\-flavoured markdown output
126.TP
127.B json
128JSON output with structured data
129.RE
130.TP
131.B -o\-file \fIFILE\fR
132Write output to FILE instead of stdout.
133.TP
134.B \-\-include\-articles
135Include the original articles in JSON output. Only applicable when
136.B -o json
137is used.
138.SS Interface Options
139.TP
140.B \-D\fR,\fB \-\-dry\-run
141Validate configuration and preview what would happen without making any LLM
142API calls. Useful for:
143.RS 4
144.TP 2
145\(bu
146Validating feeds file and configuration
147.TP 2
148\(bu
149Checking article counts and filtering results
150.TP 2
151\(bu
152Estimating token usage before running
153.TP 2
154\(bu
155Testing network connectivity to feeds
156.RE
157.TP
158.B \-t\fR,\fB -t
159Enable the TUI interface with a progress bar, live article counters, and
160elapsed time display. The TUI supports keyboard navigation (j/k, arrows,
161space, b, g/G) and mouse wheel scrolling.
162.TP
163.B \-v\fR,\fB \-\-verbose
164Enable verbose logging. Shows detailed progress information during execution.
165.SS General Options
166.TP
167.B \-\-version
168Show version information and exit.
169.TP
170.B \-h\fR,\fB \-\-help
171Show this help message and exit.
172.SH ENVIRONMENT VARIABLES
173All configuration options can be set via environment variables with the
174.B LLM_AGGREGATOR_
175prefix:
176.TP
177.B LLM_AGGREGATOR_API_KEY
178LLM API key (required if not provided via \-\-api\-key)
179.TP
180.B LLM_AGGREGATOR_BASE_URL
181API base URL (default: "https://api.deepseek.com")
182.TP
183.B LLM_AGGREGATOR_MODEL
184Model name (default: "deepseek-chat")
185.TP
186.B LLM_AGGREGATOR_MAX_TOKENS
187Maximum tokens in response (default: 4000)
188.TP
189.B LLM_AGGREGATOR_TEMPERATURE
190Sampling temperature (default: 0.7)
191.TP
192.B LLM_AGGREGATOR_SYSTEM_PROMPT
193Custom system prompt
194.TP
195.B LLM_AGGREGATOR_MAX_ARTICLES_PER_FEED
196Maximum articles per feed (default: 10)
197.TP
198.B LLM_AGGREGATOR_MAX_DAYS_OLD
199Maximum article age in days (default: 7)
200.TP
201.B LLM_AGGREGATOR_MAX_TOTAL_ARTICLES
202Maximum total articles (default: 20)
203.TP
204.B LLM_AGGREGATOR_INCLUDE_KEYWORDS
205Comma\-separated include keywords
206.TP
207.B LLM_AGGREGATOR_EXCLUDE_KEYWORDS
208Comma\-separated exclude keywords
209.TP
210.B LLM_AGGREGATOR_OUTPUT
211Output format (default: "text")
212.TP
213.B LLM_AGGREGATOR_OUTPUT_FILE
214Output file path
215.TP
216.B LLM_AGGREGATOR_INCLUDE_ARTICLES
217Include articles in JSON output (true/false)
218.SH CONFIGURATION FILE
219Configuration can also be provided via a TOML file at:
220.PP
221.RS 4
222~/.config/llm_aggregator/config.toml
223.RE
224.PP
225See
226.BR llm_aggregator (5)
227for details on the configuration file format.
228.PP
229The precedence order for configuration (highest to lowest) is:
230.RS 4
231.TP 2
2321.
233Command\-line arguments
234.TP 2
2352.
236Environment variables
237.TP 2
2383.
239Configuration file
240.TP 2
2414.
242Built\-in defaults
243.RE
244.SH EXAMPLES
245.SS Basic Usage
246.PP
247Summarise tech news from a list of feeds:
248.PP
249.RS 4
250.nf
251llm_aggregator -f feeds.txt \\
252    -p "What are the latest AI\-related trends in free software?"
253.fi
254.RE
255.SS Validating Configuration (Dry Run)
256.PP
257Validate configuration and preview articles before making any LLM API calls:
258.PP
259.RS 4
260.nf
261llm_aggregator -f feeds.txt -p "Summarise news" -D
262.fi
263.RE
264.PP
265This shows article counts, filtering statistics, token estimates, and the
266prompt that would be sent. No API key is required for dry-run mode.
267.SS Using TUI
268.PP
269Enable the TUI interface with a progress bar:
270.PP
271.RS 4
272.nf
273llm_aggregator -f feeds.txt -p "Summarise tech news" -t
274.fi
275.RE
276.SS JSON Output with Articles
277.PP
278Output to a JSON file with original articles included:
279.PP
280.RS 4
281.nf
282llm_aggregator -f feeds.txt -p "Analyse AI developments" \\
283    -o json -o-file analysis.json \-\-include\-articles
284.fi
285.RE
286.SS Filtering by Keywords
287.PP
288Only include articles about Linux or open source:
289.PP
290.RS 4
291.nf
292llm_aggregator -f feeds.txt -p "Linux news" \\
293    \-\-include\-keywords linux,opensource \-\-max\-days\-old 3
294.fi
295.RE
296.SS Custom Model and API Endpoint
297.PP
298Use a custom model with a higher token limit or local endpoint:
299.PP
300.RS 4
301.nf
302llm_aggregator -f feeds.txt -p "Code analysis" \\
303    -m deepseek-reasoner \-\-max-tokens 8000
304
305llm_aggregator -f feeds.txt -p "Summarise news" \\
306    \-\-base-url "http://localhost:11434/v1" -m llama3
307.fi
308.RE
309.SS Custom System Prompt
310.PP
311Provide a custom system prompt for different analysis styles:
312.PP
313.RS 4
314.nf
315llm_aggregator -f feeds.txt \\
316    -p "Identify security vulnerabilities" \\
317    \-\-system-prompt "You are a security expert. Focus on identifying \\
318potential vulnerabilities, data breaches, and security advisories."
319.fi
320.RE
321.SH FEEDS FILE FORMAT
322The feeds file should contain one RSS or Atom feed URL per line. Blank lines
323and lines starting with
324.B #
325are ignored as comments. Example:
326.PP
327.RS 4
328.nf
329# Technology news
330https://news.ycombinator.com/rss
331https://lwn.net/headlines/newrss
332
333# Programming
334https://opensource.com/feed
335https://www.phoronix.com/rss.php
336.fi
337.RE
338.SH DEPENDENCIES
339.B llm_aggregator
340uses the following Go libraries:
341.TP 2
342\(bu
343.BR gofeed
344\- RSS/Atom/JSON feed parser
345.TP 2
346\(bu
347.BR openai-go
348\- OpenAI API client
349.TP 2
350\(bu
351.BR bubbletea
352\- TUI framework
353.TP 2
354\(bu
355.BR lipgloss
356\- Terminal styling
357.TP 2
358\(bu
359.BR go-arg
360\- Argument parsing
361.TP 2
362\(bu
363.BR tiktoken-go
364\- Token counting
365.TP 2
366\(bu
367.BR viper
368\- Configuration management
369.TP 2
370\(bu
371.BR goquery
372\- HTML scraping
373.SH EXIT STATUS
374.TP
375.B 0
376Success
377.TP
378.B 1
379Error (invalid arguments, missing API key, API error, etc.)
380.SH FILES
381.TP
382.B ~/.config/llm_aggregator/config.toml
383Default location for TOML configuration file.
384.SH SEE ALSO
385.BR llm_aggregator (5)
386for configuration file documentation.
387.PP
388Project homepage: https://codeberg.org/maxwelljensen/llm_aggregator
389.SH AUTHOR
390Written by Maxwell Jensen.
391.SH REPORTING BUGS
392Report bugs at: https://codeberg.org/maxwelljensen/llm_aggregator/issues
393.SH COPYRIGHT
394Copyright \(co 2026 Maxwell Jensen.
395.br
396Licensed under the European Union Public Licence 1.2 (EUPL\-1.2).
397.br
398See
399.BR LICENCE.txt
400for full licence details.