1.\" Man page for llm_aggregator configuration file
  2.TH LLM_AGGREGATOR 5 "23 April 2026" "0.9.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.SH "[system]"
101Options related to the LLM system prompt.
102.TP
103.B prompt = \fI"string"\fR
104User prompt for summarisation/analysis. This is a required argument that
105instructs the LLM on what to do with the aggregated feed content.
106.br
107Note: This is a required command\-line argument and cannot be set via
108environment variable or config file.
109.TP
110.B system_prompt = \fI"string"\fR
111Custom system prompt for the LLM. The system prompt instructs the AI on
112how to behave and what format to use in its responses.
113.br
114.br
115Default:
116.br
117.nf
118  "You are an expert analyst and summariser.
119   You analyse content from multiple sources and provide
120   concise, insightful summaries based on user requests.
121   Focus on key points, trends, and important information."
122.fi
123.br
124.br
125The system prompt can span multiple lines using TOML's multi\-line string
126syntax (triple quotes).
127.SH "[output]"
128Options for controlling output format and destination.
129.TP
130.B output = \fI"string"\fR
131Output format. Must be one of: "text", "json", or "markdown".
132.br
133Default: "text"
134.TP
135.B output_file = \fI"string"\fR
136Optional file path to write output to. If not specified, output is written
137to stdout.
138.br
139Example: output_file = "/tmp/summary.txt"
140.TP
141.B include_articles = \fIboolean\fR
142Include the original articles in JSON output. Only applicable when
143.B output
144is set to "json".
145.br
146Default: false
147.SH "[runtime]"
148Options controlling runtime behaviour and output modes.
149.TP
150.B tui = \fIboolean\fR
151Enable the terminal user interface (TUI) mode with a colourful progress
152bar, live article counters, elapsed time, and a scrollable summary view.
153When enabled, the program runs interactively with keyboard navigation
154support (j/k, arrows, space, b, g/G for scrolling and q/Ctrl+C to quit).
155Markdown content from the LLM is rendered with proper styling.
156.br
157Default: false
158.TP
159.B verbose = \fIboolean\fR
160Enable verbose output mode. Shows detailed progress information including
161feed fetching status, article filtering details, token usage estimates,
162and LLM API interaction progress.
163.br
164Default: false
165.TP
166.B dry_run = \fIboolean\fR
167Validate configuration and preview what would happen without making any
168LLM API calls. Useful for validating the feeds file and configuration,
169checking article counts and filtering results, and anything else that can
170be done "offline".
171.br
172Default: false
173.SH EXAMPLE CONFIGURATION
174Below is a complete example configuration file:
175.PP
176.RS 4
177.nf
178# llm_aggregator configuration file
179# Location: ~/.config/llm_aggregator/config.toml
180
181# Feed aggregation options
182max_articles_per_feed = 10
183max_days_old = 7
184max_total_articles = 20
185
186# Content filtering (comma-separated keywords)
187# include_keywords = "linux,opensource"
188# exclude_keywords = "windows,microsoft"
189
190# LLM API options
191# api_key = "your_api_key_here"  # Can also be set via LLM_AGGREGATOR_API_KEY env var
192model = "deepseek-chat"
193max_tokens = 4000
194temperature = 0.7
195
196# System prompt for LLM API
197system_prompt = """You are an expert analyst and summariser.
198You analyse content from multiple sources and provide
199concise, insightful summaries based on user requests.
200Focus on key points, trends, and important information."""
201
202# Output options
203output = "text"  # Options: text, json, markdown
204# output_file = ""  # Optional output file path
205include_articles = false
206
207# Runtime options
208# tui = false  # Enable TUI mode (default: false)
209# verbose = false  # Enable verbose output (default: false)
210# dry_run = false  # Validate config without API calls (default: false)
211.fi
212.RE
213.PP
214A more feature\-rich example with filtering and custom API settings:
215.PP
216.RS 4
217.nf
218# Feed aggregation options
219max_articles_per_feed = 15
220max_days_old = 3
221max_total_articles = 30
222
223# Content filtering
224include_keywords = "linux,kernel,open source,AI"
225exclude_keywords = "windows, proprietary"
226
227# LLM API options
228# api_key = "sk-..."  # Use env var in production
229base_url = "https://api.deepseek.com"
230model = "deepseek-chat"
231max_tokens = 6000
232temperature = 0.5
233
234# Custom system prompt for technical content analysis
235system_prompt = """You are a technical analyst specialising in
236open source software and cybersecurity. Provide detailed,
237accurate summaries focusing on technical implications
238and practical applications."""
239
240# Output options
241output = "markdown"
242include_articles = true
243
244# Runtime options
245tui = true  # Enable TUI mode
246verbose = true  # Show progress details
247dry_run = false  # Perform actual LLM API call
248.fi
249.RE
250.SH CONFIGURATION PRECEDENCE
251Configuration options are resolved in the following order (highest to lowest):
252.TP 2
2531.
254Command\-line arguments (e.g., \-\-model, \-\-output)
255.TP 2
2562.
257Environment variables (e.g., LLM_AGGREGATOR_MODEL, LLM_AGGREGATOR_OUTPUT)
258.TP 2
2593.
260Configuration file (~/.config/llm_aggregator/config.toml)
261.TP 2
2624.
263Built\-in defaults
264.PP
265This means any option specified on the command line will override both the
266environment variable and the configuration file for that invocation.
267.SH ENVIRONMENT VARIABLES
268The following environment variables can be used to set configuration options.
269They take precedence over the configuration file but not over command\-line
270arguments.
271.TP
272.B LLM_AGGREGATOR_API_KEY
273API key for the LLM service.
274.TP
275.B LLM_AGGREGATOR_BASE_URL
276API base URL.
277.TP
278.B LLM_AGGREGATOR_MODEL
279Model name.
280.TP
281.B LLM_AGGREGATOR_MAX_TOKENS
282Maximum tokens in response.
283.TP
284.B LLM_AGGREGATOR_TEMPERATURE
285Sampling temperature.
286.TP
287.B LLM_AGGREGATOR_SYSTEM_PROMPT
288Custom system prompt.
289.TP
290.B LLM_AGGREGATOR_MAX_ARTICLES_PER_FEED
291Maximum articles per feed.
292.TP
293.B LLM_AGGREGATOR_MAX_DAYS_OLD
294Maximum article age in days.
295.TP
296.B LLM_AGGREGATOR_MAX_TOTAL_ARTICLES
297Maximum total articles.
298.TP
299.B LLM_AGGREGATOR_INCLUDE_KEYWORDS
300Comma\-separated include keywords.
301.TP
302.B LLM_AGGREGATOR_EXCLUDE_KEYWORDS
303Comma\-separated exclude keywords.
304.TP
305.B LLM_AGGREGATOR_OUTPUT
306Output format (text/json/markdown).
307.TP
308.B LLM_AGGREGATOR_OUTPUT_FILE
309Output file path.
310.TP
311.B LLM_AGGREGATOR_INCLUDE_ARTICLES
312Include articles in JSON output (true/false).
313.TP
314.B LLM_AGGREGATOR_DRY_RUN
315Validate configuration without making LLM API calls (true/false).
316.TP
317.B LLM_AGGREGATOR_TUI
318Enable TUI mode (true/false).
319.SH SECURITY CONSIDERATIONS
320.TP 2
321\(bu
322Avoid storing API keys in the configuration file. Use the
323.B LLM_AGGREGATOR_API_KEY
324environment variable instead.
325.TP 2
326\(bu
327The configuration file should have restrictive permissions (mode 600) to
328prevent other users from reading your API key if it is stored in the file.
329.TP 2
330\(bu
331Command\-line arguments may be visible to other users via process listings.
332Use environment variables for sensitive data in shared environments.
333.SH FILES
334.TP
335.B ~/.config/llm_aggregator/config.toml
336Primary configuration file location.
337.TP
338.B /etc/llm_aggregator/config.toml
339System\-wide configuration (if applicable).
340.SH SEE ALSO
341.BR llm_aggregator (1)
342.SH AUTHOR
343Written by Maxwell Jensen.
344.SH REPORTING BUGS
345Report bugs at: https://codeberg.org/maxwelljensen/llm_aggregator/issues
346.SH COPYRIGHT
347Copyright \(co 2026 Maxwell Jensen.
348.br
349Licensed under the European Union Public Licence 1.2 (EUPL\-1.2).
350.br
351See
352.BR LICENCE.txt
353for full licence details.