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