My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1# River CLI Examples
2
3This document shows how to use the River feed management CLI.
4
5## Basic Setup
6
7First, build the CLI:
8```bash
9dune build
10```
11
12The CLI will use `~/.river` as the default state directory, but you can override with `--state-dir`.
13
14## State Directory Structure
15
16The CLI creates and manages:
17```
18~/.river/
19├── users/ # JSON files containing user data
20│ ├── alice.json # User configuration and feed list
21│ └── bob.json
22└── feeds/
23 └── user/ # Aggregated Atom feeds
24 ├── alice.xml # All posts from alice's feeds
25 └── bob.xml
26```
27
28## User Management
29
30### Add a new user
31```bash
32river-cli user add alice --name "Alice Smith" --email "alice@example.com"
33```
34
35### List all users
36```bash
37river-cli user list
38```
39
40### Show user details
41```bash
42river-cli user show alice
43```
44
45### Remove a user
46```bash
47river-cli user remove alice
48```
49
50## Feed Management
51
52### Add a feed to a user
53```bash
54river-cli user add-feed alice --name "Alice's Blog" --url "https://alice.example.com/feed.xml"
55river-cli user add-feed alice --name "Tech News" --url "https://technews.example.com/rss"
56```
57
58### Remove a feed from a user
59```bash
60river-cli user remove-feed alice --url "https://alice.example.com/feed.xml"
61```
62
63## Synchronization
64
65### Sync feeds for a specific user
66```bash
67river-cli sync alice
68```
69
70### Sync all users
71```bash
72river-cli sync
73```
74
75### Sync with different log levels
76```bash
77# Info level (default shows main operations)
78river-cli sync alice --verbosity=info
79
80# Debug level (shows detailed HTTP and parsing logs)
81river-cli sync alice --verbosity=debug
82
83# Quiet mode (no logs)
84river-cli sync alice --quiet
85```
86
87## Example Workflow
88
891. **Setup users and feeds**:
90```bash
91# Add a user
92river-cli user add alice --name "Alice Smith" --email "alice@example.com"
93
94# Add some feeds
95river-cli user add-feed alice --name "Alice's Blog" --url "https://alice.example.com/feed.xml"
96river-cli user add-feed alice --name "HackerNews" --url "https://hnrss.org/frontpage"
97
98# View the configuration
99river-cli user show alice
100```
101
1022. **Initial sync**:
103```bash
104river-cli sync alice --verbosity=debug
105```
106
1073. **Check the result**:
108The aggregated feed will be saved to `~/.river/feeds/user/alice.xml` and contains all posts from both feeds, deduplicated and sorted by date.
109
1104. **Regular sync**:
111```bash
112# Run periodically (e.g., via cron)
113river-cli sync alice
114```
115
116## Using Custom State Directory
117
118```bash
119# Use a custom directory
120river-cli --state-dir ./my-feeds user add alice --name "Alice" --email "alice@example.com"
121river-cli --state-dir ./my-feeds user add-feed alice --name "Feed" --url "https://example.com/feed.xml"
122river-cli --state-dir ./my-feeds sync alice
123```
124
125## JSON User File Format
126
127User files (e.g., `~/.river/users/alice.json`) contain:
128```json
129{
130 "username": "alice",
131 "fullname": "Alice Smith",
132 "email": "alice@example.com",
133 "feeds": [
134 {
135 "name": "Alice's Blog",
136 "url": "https://alice.example.com/feed.xml"
137 },
138 {
139 "name": "HackerNews",
140 "url": "https://hnrss.org/frontpage"
141 }
142 ],
143 "last_synced": "2025-09-29T14:30:00Z"
144}
145```
146
147## Logging
148
149The CLI uses structured logging with multiple levels:
150
151- **Debug**: Detailed HTTP requests, TLS info, feed parsing details
152- **Info**: Main operations (fetching feeds, creating users, sync progress)
153- **Warning**: Recoverable issues
154- **Error**: Failures and exceptions
155- **Quiet**: No output
156
157### Logging Options
158```bash
159# Specific log level
160--verbosity=debug|info|warning|error|quiet
161
162# Short flags
163-v, --verbose # Increase verbosity (repeatable)
164-q, --quiet # Quiet mode
165
166# Color control
167--color=auto|always|never
168```
169
170### Example with different log levels
171```bash
172# See all details including HTTP requests and parsing
173river-cli sync alice --verbosity=debug
174
175# See main operations only
176river-cli sync alice --verbosity=info
177
178# Completely silent
179river-cli sync alice --quiet
180```
181
182## Features
183
184- **Deduplication**: Posts with same ID are not duplicated
185- **Sorting**: Posts are sorted by date (newest first)
186- **Error handling**: Failed feeds don't stop sync of other feeds
187- **Structured logging**: Uses Logs library with fmt and logs.cli integration
188- **Feed formats**: Supports both Atom and RSS2 feeds
189- **State persistence**: User configuration and aggregated feeds are saved locally