1# Usage guide
  2
  3## Installation
  4
  5```bash
  6# From source
  7go build ./cmd/llm_aggregator.go
  8```
  9
 10Or grab the latest binary in the
 11[Releases](https://codeberg.org/maxwelljensen/llm_aggregator/releases) section.
 12
 13## Man pages
 14
 15`man`` pages ship with the project in `docs/`:
 16
 17| File | Section | Description |
 18|------|---------|-------------|
 19| `docs/llm_aggregator.1` | 1 | Full command reference |
 20| `docs/llm_aggregator.5` | 5 | Configuration file reference |
 21
 22Install to your `$MANPATH`, then run:
 23
 24```bash
 25man llm_aggregator    # section 1: command options
 26man 5 llm_aggregator  # section 5: config file format
 27```
 28
 29## Basic usage
 30
 31```bash
 32llm_aggregator --feeds-file FEEDS-FILE --prompt PROMPT [OPTIONS]...
 33```
 34
 35`llm_aggregator` reads a list of RSS feed URLs, fetches the articles, filters
 36them by date and keywords, and sends a summary request to the LLM. The
 37result is printed to the terminal in your chosen format (text, markdown, or
 38JSON).
 39
 40---
 41
 42## Feed sources
 43
 44### Feeds file
 45
 46Create a plain text file with one RSS/Atom feed URL per line. Lines starting
 47with `#` are comments; empty lines are skipped.
 48
 49```bash
 50# Example feeds.txt
 51https://news.ycombinator.com/rss
 52https://lwn.net/headlines/newrss
 53
 54# Linux news
 55https://opensource.com/feed
 56https://www.phoronix.com/rss.php
 57```
 58
 59### stdin
 60
 61Read a single RSS/Atom feed directly from stdin:
 62
 63```bash
 64curl -s https://example.com/feed.xml | llm_aggregator --stdin -p "Summarise"
 65```
 66
 67### Combining both
 68
 69```bash
 70llm_aggregator -f feeds.txt --stdin -p "Summarise all"
 71```
 72
 73---
 74
 75## Command reference
 76
 77### Required
 78
 79| Flag | Description |
 80|------|-------------|
 81| `-f, --feeds-file FILE` | Path to file containing RSS feed URLs (one per line) |
 82| `-p, --prompt PROMPT` | User prompt for summarisation/analysis |
 83
 84> [!NOTE]
 85> `-f/--feeds-file` is required only if not using `--stdin`
 86
 87### Feed & filtering options
 88
 89| Flag | Default | Description |
 90|------|---------|-------------|
 91| `-f, --feeds-file FILE` | — | Path to file containing RSS feed URLs (one per line) |
 92| `--stdin` | `false` | Read a single RSS/Atom feed from stdin (can be combined with `-f`) |
 93| `-n, --max-articles-per-feed N` | `10` | Maximum articles to fetch from each feed |
 94| `-d, --max-days-old N` | `7` | Only include articles from the last N days (0 for all) |
 95| `--max-total-articles N` | `20` | Maximum total articles to process |
 96| `-i, --include-keywords LIST` | — | Comma-separated keywords to include (case-insensitive) |
 97| `-e, --exclude-keywords LIST` | — | Comma-separated keywords to exclude (case-insensitive) |
 98
 99### LLM API options
100
101| Flag | Default | Description |
102|------|---------|-------------|
103| `--api-key KEY` | `$LLM_AGGREGATOR_API_KEY` | API key |
104| `-m, --model MODEL` | `deepseek-chat` | Model name |
105| `--base-url URL` | `https://api.deepseek.com` | API base URL |
106| `--max-tokens N` | `4000` | Maximum tokens in response |
107| `--temperature VALUE` | `0.7` | Sampling temperature (0.0 to 1.0) |
108| `--timeout N` | `300` | LLM request timeout in seconds |
109| `--system-prompt TEXT` | — | Custom system prompt for LLM |
110
111### Output options
112
113| Flag | Default | Description |
114|------|---------|-------------|
115| `-o, --output FORMAT` | `text` | Output format: `text`, `markdown`, or `json` |
116| `--output-file FILE` | — | Write output to FILE instead of STDOUT |
117| `--include-articles` | `false` | Include original articles in JSON output |
118| `-P, --plain` | `false` | Output only the raw LLM response without formatting or metadata |
119
120### Interface options
121
122| Flag | Description |
123|------|-------------|
124| `-t, --tui` | Enable TUI interface with progress bar |
125| `-v, --verbose` | Enable verbose logging |
126| `-D, --dry-run` | Validate config, show article statistics, and exit without making LLM API calls |
127
128### Other
129
130| Flag | Description |
131|------|-------------|
132| `-h, --help` | Show help message and exit |
133| `--version` | Show version information and exit |
134
135---
136
137## Examples
138
139### Basic summarisation
140
141```bash
142llm_aggregator -f feeds.txt -p "What are the latest AI-related trends in free software?"
143```
144
145### Custom model and higher token limit
146
147```bash
148llm_aggregator -f feeds.txt -p "Code analysis" \
149    -m deepseek-reasoner --max-tokens 8000
150```
151
152### Local Ollama instance
153
154```bash
155llm_aggregator -f feeds.txt -p "Summarise news" \
156    --base-url "http://localhost:11434/v1" -m llama3
157```
158
159### Keyword filtering
160
161Include only articles about Linux or open source:
162
163```bash
164llm_aggregator -f feeds.txt -p "Linux news" \
165    -i linux,opensource -d 3
166```
167
168Exclude articles about Windows:
169
170```bash
171llm_aggregator -f feeds.txt -p "Tech news" \
172    -e windows,microsoft
173```
174
175### JSON output with articles
176
177```bash
178llm_aggregator -f feeds.txt -p "Analyse AI developments" \
179    -o json --output-file analysis.json --include-articles
180```
181
182### TUI mode
183
184```bash
185llm_aggregator -f feeds.txt -p "Summarise tech news" -t
186```
187
188---
189
190## Configuration
191
192`llm_aggregator` supports multiple configuration sources with the following
193precedence order (highest to lowest):
194
1951. **Command-line arguments** — Override everything
1962. **Environment variables** — Start with `LLM_AGGREGATOR_` prefix
1973. **Configuration file** — `~/.config/llm_aggregator/config.toml`
1984. **Built-in defaults**
199
200### Configuration file
201
202Create a TOML file at `~/.config/llm_aggregator/config.toml`:
203
204```toml
205# Feed aggregation options
206max_articles_per_feed = 10
207max_days_old = 7
208max_total_articles = 20
209
210# Content filtering (comma-separated keywords)
211# include_keywords = "linux,opensource"
212# exclude_keywords = "windows,microsoft"
213
214# LLM API options
215# api_key = "your_api_key_here"  # Can also be set via LLM_AGGREGATOR_API_KEY env var
216# base_url = "https://api.deepseek.com"  # Optional custom API endpoint
217model = "deepseek-chat"
218max_tokens = 4000
219temperature = 0.7
220
221# System prompt for LLM API
222system_prompt = """You are an expert analyst and summariser.
223You analyse content from multiple sources and provide
224concise, insightful summaries based on user requests.
225Focus on key points, trends, and important information."""
226
227# Output options
228output = "text"  # Options: text, json, markdown
229# output_file = ""  # Optional output file path
230include_articles = false
231```
232
233### Environment variables
234
235| Variable | Default | Description |
236|----------|---------|-------------|
237| `LLM_AGGREGATOR_API_KEY` | — | LLM API key |
238| `LLM_AGGREGATOR_BASE_URL` | `https://api.deepseek.com` | API base URL |
239| `LLM_AGGREGATOR_MODEL` | `deepseek-chat` | Model name |
240| `LLM_AGGREGATOR_MAX_TOKENS` | `4000` | Maximum tokens in response |
241| `LLM_AGGREGATOR_TEMPERATURE` | `0.7` | Sampling temperature |
242| `LLM_AGGREGATOR_TIMEOUT` | `300` | LLM request timeout in seconds |
243| `LLM_AGGREGATOR_SYSTEM_PROMPT` | — | Custom system prompt |
244| `LLM_AGGREGATOR_MAX_ARTICLES_PER_FEED` | `10` | Maximum articles per feed |
245| `LLM_AGGREGATOR_MAX_DAYS_OLD` | `7` | Maximum article age in days |
246| `LLM_AGGREGATOR_MAX_TOTAL_ARTICLES` | `20` | Maximum total articles |
247| `LLM_AGGREGATOR_INCLUDE_KEYWORDS` | — | Comma-separated include keywords |
248| `LLM_AGGREGATOR_EXCLUDE_KEYWORDS` | — | Comma-separated exclude keywords |
249| `LLM_AGGREGATOR_OUTPUT` | `text` | Output format |
250| `LLM_AGGREGATOR_OUTPUT_FILE` | — | Output file path |
251| `LLM_AGGREGATOR_INCLUDE_ARTICLES` | `false` | Include articles in JSON output |
252| `LLM_AGGREGATOR_PLAIN` | `false` | Plain output without metadata |
253| `LLM_AGGREGATOR_STDIN` | `false` | Read RSS/Atom feed from stdin |
254| `LLM_AGGREGATOR_FEEDS_FILE` | — | Feeds file path |
255| `LLM_AGGREGATOR_TUI` | `false` | Enable TUI mode |
256| `LLM_AGGREGATOR_DRY_RUN` | `false` | Dry-run mode |
257| `LLM_AGGREGATOR_VERBOSE` | `false` | Verbose logging |