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