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### Feed & filtering options
 85
 86| Flag | Default | Description |
 87|------|---------|-------------|
 88| `-n, --max-articles-per-feed N` | `10` | Maximum articles to fetch from each feed |
 89| `-d, --max-days-old N` | `7` | Only include articles from the last N days (0 for all) |
 90| `--max-total-articles N` | `20` | Maximum total articles to process |
 91| `-i, --include-keywords LIST` | — | Comma-separated keywords to include (case-insensitive) |
 92| `-e, --exclude-keywords LIST` | — | Comma-separated keywords to exclude (case-insensitive) |
 93
 94### LLM API options
 95
 96| Flag | Default | Description |
 97|------|---------|-------------|
 98| `--api-key KEY` | `$LLM_AGGREGATOR_API_KEY` | API key |
 99| `-m, --model MODEL` | `deepseek-chat` | Model name |
100| `--base-url URL` | `https://api.deepseek.com` | API base URL |
101| `--max-tokens N` | `4000` | Maximum tokens in response |
102| `--temperature VALUE` | `0.7` | Sampling temperature (0.0 to 1.0) |
103| `--timeout N` | `300` | LLM request timeout in seconds |
104| `--system-prompt TEXT` | — | Custom system prompt for LLM |
105
106### Output options
107
108| Flag | Default | Description |
109|------|---------|-------------|
110| `-o, --output FORMAT` | `text` | Output format: `text`, `markdown`, or `json` |
111| `--output-file FILE` | — | Write output to FILE instead of STDOUT |
112| `--include-articles` | `false` | Include original articles in JSON output |
113| `-P, --plain` | `false` | Output only the raw LLM response without formatting or metadata |
114
115### Interface options
116
117| Flag | Description |
118|------|-------------|
119| `-t, --tui` | Enable TUI interface with progress bar |
120| `-v, --verbose` | Enable verbose logging |
121| `-D, --dry-run` | Validate config, show article statistics, and exit without making LLM API calls |
122
123### Other
124
125| Flag | Description |
126|------|-------------|
127| `-h, --help` | Show help message and exit |
128| `--version` | Show version information and exit |
129
130---
131
132## Examples
133
134### Basic summarisation
135
136```bash
137llm_aggregator -f feeds.txt -p "What are the latest AI-related trends in free software?"
138```
139
140### Custom model and higher token limit
141
142```bash
143llm_aggregator -f feeds.txt -p "Code analysis" \
144    -m deepseek-reasoner --max-tokens 8000
145```
146
147### Local Ollama instance
148
149```bash
150llm_aggregator -f feeds.txt -p "Summarise news" \
151    --base-url "http://localhost:11434/v1" -m llama3
152```
153
154### Keyword filtering
155
156Include only articles about Linux or open source:
157
158```bash
159llm_aggregator -f feeds.txt -p "Linux news" \
160    -i linux,opensource -d 3
161```
162
163Exclude articles about Windows:
164
165```bash
166llm_aggregator -f feeds.txt -p "Tech news" \
167    -e windows,microsoft
168```
169
170### JSON output with articles
171
172```bash
173llm_aggregator -f feeds.txt -p "Analyse AI developments" \
174    -o json --output-file analysis.json --include-articles
175```
176
177### TUI mode
178
179```bash
180llm_aggregator -f feeds.txt -p "Summarise tech news" -t
181```
182
183---
184
185## Configuration
186
187`llm_aggregator` supports multiple configuration sources with the following
188precedence order (highest to lowest):
189
1901. **Command-line arguments** — Override everything
1912. **Environment variables** — Start with `LLM_AGGREGATOR_` prefix
1923. **Configuration file** — `~/.config/llm_aggregator/config.toml`
1934. **Built-in defaults**
194
195### Configuration file
196
197Create a TOML file at `~/.config/llm_aggregator/config.toml`:
198
199```toml
200# Feed aggregation options
201max_articles_per_feed = 10
202max_days_old = 7
203max_total_articles = 20
204
205# Content filtering (comma-separated keywords)
206# include_keywords = "linux,opensource"
207# exclude_keywords = "windows,microsoft"
208
209# LLM API options
210# api_key = "your_api_key_here"  # Can also be set via LLM_AGGREGATOR_API_KEY env var
211# base_url = "https://api.deepseek.com"  # Optional custom API endpoint
212model = "deepseek-chat"
213max_tokens = 4000
214temperature = 0.7
215
216# System prompt for LLM API
217system_prompt = """You are an expert analyst and summariser.
218You analyse content from multiple sources and provide
219concise, insightful summaries based on user requests.
220Focus on key points, trends, and important information."""
221
222# Output options
223output = "text"  # Options: text, json, markdown
224# output_file = ""  # Optional output file path
225include_articles = false
226```
227
228### Environment variables
229
230| Variable | Default | Description |
231|----------|---------|-------------|
232| `LLM_AGGREGATOR_API_KEY` | — | LLM API key |
233| `LLM_AGGREGATOR_BASE_URL` | `https://api.deepseek.com` | API base URL |
234| `LLM_AGGREGATOR_MODEL` | `deepseek-chat` | Model name |
235| `LLM_AGGREGATOR_MAX_TOKENS` | `4000` | Maximum tokens in response |
236| `LLM_AGGREGATOR_TEMPERATURE` | `0.7` | Sampling temperature |
237| `LLM_AGGREGATOR_TIMEOUT` | `300` | LLM request timeout in seconds |
238| `LLM_AGGREGATOR_SYSTEM_PROMPT` | — | Custom system prompt |
239| `LLM_AGGREGATOR_MAX_ARTICLES_PER_FEED` | `10` | Maximum articles per feed |
240| `LLM_AGGREGATOR_MAX_DAYS_OLD` | `7` | Maximum article age in days |
241| `LLM_AGGREGATOR_MAX_TOTAL_ARTICLES` | `20` | Maximum total articles |
242| `LLM_AGGREGATOR_INCLUDE_KEYWORDS` | — | Comma-separated include keywords |
243| `LLM_AGGREGATOR_EXCLUDE_KEYWORDS` | — | Comma-separated exclude keywords |
244| `LLM_AGGREGATOR_OUTPUT` | `text` | Output format |
245| `LLM_AGGREGATOR_OUTPUT_FILE` | — | Output file path |
246| `LLM_AGGREGATOR_INCLUDE_ARTICLES` | `false` | Include articles in JSON output |
247| `LLM_AGGREGATOR_PLAIN` | `false` | Plain output without metadata |
248| `LLM_AGGREGATOR_STDIN` | `false` | Read RSS/Atom feed from stdin |
249| `LLM_AGGREGATOR_FEEDS_FILE` | — | Feeds file path |
250| `LLM_AGGREGATOR_TUI` | `false` | Enable TUI mode |
251| `LLM_AGGREGATOR_DRY_RUN` | `false` | Dry-run mode |
252| `LLM_AGGREGATOR_VERBOSE` | `false` | Verbose logging |