1.\" Man page for llm_aggregator configuration file
  2.TH LLM_AGGREGATOR 5 "27 April 2026" "1.0.0" "File Formats"
  3.SH NAME
  4llm_aggregator.conf \- configuration file for llm_aggregator
  5.SH DESCRIPTION
  6The
  7.B llm_aggregator
  8configuration file is a TOML file that allows users to set default values
  9for all command\-line options. This eliminates the need to specify common
 10options on every invocation.
 11.PP
 12The configuration file is read from:
 13.PP
 14.RS 4
 15~/.config/llm_aggregator/config.toml
 16.RE
 17.PP
 18If the file does not exist, default values are used for all options.
 19Configuration options can still be overridden by environment variables and
 20command\-line arguments.
 21.SH FILE STRUCTURE
 22The configuration file is a TOML file with the following sections and
 23options:
 24.SH "[feed_aggregation]"
 25Options controlling how feeds are fetched and processed.
 26.TP
 27.B feeds_file = \fI"string"\fR
 28Path to a file containing RSS feed URLs, one per line. This is the input
 29file that specifies which feeds to aggregate.
 30.br
 31Note: This is a required command\-line argument and cannot be set via
 32environment variable or config file.
 33.TP
 34.B max_articles_per_feed = \fIinteger\fR
 35Maximum number of articles to fetch from each feed.
 36.br
 37Default: 10
 38.TP
 39.B max_days_old = \fIinteger\fR
 40Only include articles from the last N days. Set to 0 to include all articles
 41regardless of age.
 42.br
 43Default: 7
 44.TP
 45.B max_total_articles = \fIinteger\fR
 46Maximum total number of articles to process across all feeds.
 47.br
 48Default: 20
 49.SH "[filtering]"
 50Options for filtering article content by keywords.
 51.TP
 52.B include_keywords = \fI"string"\fR
 53Comma\-separated list of keywords to include. Only articles containing at
 54least one of these keywords (case\-insensitive) will be processed.
 55.br
 56Example: include_keywords = "linux,opensource"
 57.TP
 58.B exclude_keywords = \fI"string"\fR
 59Comma\-separated list of keywords to exclude. Any article containing one of
 60these keywords (case\-insensitive) will be filtered out.
 61.br
 62Example: exclude_keywords = "windows,microsoft"
 63.SH "[llm_api]"
 64Options for the LLM API connection and behaviour.
 65.TP
 66.B api_key = \fI"string"\fR
 67OpenAI\-compatible API key. Can also be set via the
 68.B LLM_AGGREGATOR_API_KEY
 69environment variable.
 70.br
 71Note: It is generally safer to set this via the environment variable rather
 72than in the configuration file.
 73.TP
 74.B base_url = \fI"string"\fR
 75API base URL for the LLM service.
 76.br
 77Default: "https://api.deepseek.com"
 78.br
 79Example for local Ollama: "http://localhost:11434/v1"
 80.TP
 81.B model = \fI"string"\fR
 82LLM model to use for summarisation.
 83.br
 84Default: "deepseek-chat"
 85.br
 86Common models: deepseek-chat, deepseek-reasoner, gpt-4o, llama3
 87.TP
 88.B max_tokens = \fIinteger\fR
 89Maximum number of tokens in the LLM response.
 90.br
 91Default: 4000
 92.TP
 93.B temperature = \fIfloat\fR
 94Sampling temperature for the LLM. Must be between 0.0 and 1.0.
 95.br
 96Lower values produce more deterministic output, higher values produce more
 97creative output.
 98.br
 99Default: 0.7
100.TP
101.B timeout = \fIinteger\fR
102LLM request timeout in seconds. If the LLM API call takes longer than this,
103the request is aborted.
104.br
105Default: 300
106.SH "[system]"
107Options related to the LLM system prompt.
108.TP
109.B prompt = \fI"string"\fR
110User prompt for summarisation/analysis. This is a required argument that
111instructs the LLM on what to do with the aggregated feed content.
112.br
113Note: This is a required command\-line argument and cannot be set via
114environment variable or config file.
115.TP
116.B system_prompt = \fI"string"\fR
117Custom system prompt for the LLM. The system prompt instructs the AI on
118how to behave and what format to use in its responses.
119.br
120.br
121Default:
122.br
123.nf
124  "You are an expert analyst and summariser.
125   You analyse content from multiple sources and provide
126   concise, insightful summaries based on user requests.
127   Focus on key points, trends, and important information."
128.fi
129.br
130.br
131The system prompt can span multiple lines using TOML's multi\-line string
132syntax (triple quotes).
133.SH "[output]"
134Options for controlling output format and destination.
135.TP
136.B output = \fI"string"\fR
137Output format. Must be one of: "text", "json", or "markdown".
138.br
139Default: "text"
140.TP
141.B output_file = \fI"string"\fR
142Optional file path to write output to. If not specified, output is written
143to stdout.
144.br
145Example: output_file = "/tmp/summary.txt"
146.TP
147.B include_articles = \fIboolean\fR
148Include the original articles in JSON output. Only applicable when
149.B output
150is set to "json".
151.br
152Default: false
153.SH "[runtime]"
154Options controlling runtime behaviour and output modes.
155.TP
156.B tui = \fIboolean\fR
157Enable the terminal user interface (TUI) mode with a colourful progress
158bar, live article counters, elapsed time, and a scrollable summary view.
159When enabled, the program runs interactively with keyboard navigation
160support (j/k, arrows, space, b, g/G for scrolling and q/Ctrl+C to quit).
161Markdown content from the LLM is rendered with proper styling.
162.br
163Default: false
164.TP
165.B verbose = \fIboolean\fR
166Enable verbose output mode. Shows detailed progress information including
167feed fetching status, article filtering details, token usage estimates,
168and LLM API interaction progress.
169.br
170Default: false
171.TP
172.B dry_run = \fIboolean\fR
173Validate configuration and preview what would happen without making any
174LLM API calls. Useful for validating the feeds file and configuration,
175checking article counts and filtering results, and anything else that can
176be done "offline".
177.br
178Default: false
179.SH EXAMPLE CONFIGURATION
180Below is a complete example configuration file:
181.PP
182.RS 4
183.nf
184# llm_aggregator configuration file
185# Location: ~/.config/llm_aggregator/config.toml
186
187# Feed aggregation options
188max_articles_per_feed = 10
189max_days_old = 7
190max_total_articles = 20
191
192# Content filtering (comma-separated keywords)
193# include_keywords = "linux,opensource"
194# exclude_keywords = "windows,microsoft"
195
196# LLM API options
197# api_key = "your_api_key_here"  # Can also be set via LLM_AGGREGATOR_API_KEY env var
198model = "deepseek-chat"
199max_tokens = 4000
200temperature = 0.7
201
202# System prompt for LLM API
203system_prompt = """You are an expert analyst and summariser.
204You analyse content from multiple sources and provide
205concise, insightful summaries based on user requests.
206Focus on key points, trends, and important information."""
207
208# Output options
209output = "text"  # Options: text, json, markdown
210# output_file = ""  # Optional output file path
211include_articles = false
212
213# Runtime options
214# tui = false  # Enable TUI mode (default: false)
215# verbose = false  # Enable verbose output (default: false)
216# dry_run = false  # Validate config without API calls (default: false)
217.fi
218.RE
219.PP
220A more feature\-rich example with filtering and custom API settings:
221.PP
222.RS 4
223.nf
224# Feed aggregation options
225max_articles_per_feed = 15
226max_days_old = 3
227max_total_articles = 30
228
229# Content filtering
230include_keywords = "linux,kernel,open source,AI"
231exclude_keywords = "windows, proprietary"
232
233# LLM API options
234# api_key = "sk-..."  # Use env var in production
235base_url = "https://api.deepseek.com"
236model = "deepseek-chat"
237max_tokens = 6000
238temperature = 0.5
239
240# Custom system prompt for technical content analysis
241system_prompt = """You are a technical analyst specialising in
242open source software and cybersecurity. Provide detailed,
243accurate summaries focusing on technical implications
244and practical applications."""
245
246# Output options
247output = "markdown"
248include_articles = true
249
250# Runtime options
251tui = true  # Enable TUI mode
252verbose = true  # Show progress details
253dry_run = false  # Perform actual LLM API call
254.fi
255.RE
256.SH CONFIGURATION PRECEDENCE
257Configuration options are resolved in the following order (highest to lowest):
258.TP 2
2591.
260Command\-line arguments (e.g., \-\-model, \-\-output)
261.TP 2
2622.
263Environment variables (e.g., LLM_AGGREGATOR_MODEL, LLM_AGGREGATOR_OUTPUT)
264.TP 2
2653.
266Configuration file (~/.config/llm_aggregator/config.toml)
267.TP 2
2684.
269Built\-in defaults
270.PP
271This means any option specified on the command line will override both the
272environment variable and the configuration file for that invocation.
273.SH ENVIRONMENT VARIABLES
274The following environment variables can be used to set configuration options.
275They take precedence over the configuration file but not over command\-line
276arguments.
277.TP
278.B LLM_AGGREGATOR_API_KEY
279API key for the LLM service.
280.TP
281.B LLM_AGGREGATOR_BASE_URL
282API base URL.
283.TP
284.B LLM_AGGREGATOR_MODEL
285Model name.
286.TP
287.B LLM_AGGREGATOR_MAX_TOKENS
288Maximum tokens in response.
289.TP
290.B LLM_AGGREGATOR_TEMPERATURE
291Sampling temperature.
292.TP
293.B LLM_AGGREGATOR_TIMEOUT
294LLM request timeout in seconds.
295.TP
296.B LLM_AGGREGATOR_SYSTEM_PROMPT
297Custom system prompt.
298.TP
299.B LLM_AGGREGATOR_MAX_ARTICLES_PER_FEED
300Maximum articles per feed.
301.TP
302.B LLM_AGGREGATOR_MAX_DAYS_OLD
303Maximum article age in days.
304.TP
305.B LLM_AGGREGATOR_MAX_TOTAL_ARTICLES
306Maximum total articles.
307.TP
308.B LLM_AGGREGATOR_INCLUDE_KEYWORDS
309Comma\-separated include keywords.
310.TP
311.B LLM_AGGREGATOR_EXCLUDE_KEYWORDS
312Comma\-separated exclude keywords.
313.TP
314.B LLM_AGGREGATOR_OUTPUT
315Output format (text/json/markdown).
316.TP
317.B LLM_AGGREGATOR_OUTPUT_FILE
318Output file path.
319.TP
320.B LLM_AGGREGATOR_INCLUDE_ARTICLES
321Include articles in JSON output (true/false).
322.TP
323.B LLM_AGGREGATOR_DRY_RUN
324Validate configuration without making LLM API calls (true/false).
325.TP
326.B LLM_AGGREGATOR_TUI
327Enable TUI mode (true/false).
328.SH SECURITY CONSIDERATIONS
329.TP 2
330\(bu
331Avoid storing API keys in the configuration file. Use the
332.B LLM_AGGREGATOR_API_KEY
333environment variable instead.
334.TP 2
335\(bu
336The configuration file should have restrictive permissions (mode 600) to
337prevent other users from reading your API key if it is stored in the file.
338.TP 2
339\(bu
340Command\-line arguments may be visible to other users via process listings.
341Use environment variables for sensitive data in shared environments.
342.SH FILES
343.TP
344.B ~/.config/llm_aggregator/config.toml
345Primary configuration file location.
346.TP
347.B /etc/llm_aggregator/config.toml
348System\-wide configuration (if applicable).
349.SH SEE ALSO
350.BR llm_aggregator (1)
351.SH AUTHOR
352Written by Maxwell Jensen.
353.SH REPORTING BUGS
354Report bugs at: https://codeberg.org/maxwelljensen/llm_aggregator/issues
355.SH COPYRIGHT
356Copyright \(co 2026 Maxwell Jensen.
357.br
358Licensed under the European Union Public Licence 1.2 (EUPL\-1.2).
359.br
360See
361.BR LICENCE.txt
362for full licence details.