River CLI Examples#

This document shows how to use the River feed management CLI.

Basic Setup#

First, build the CLI:

dune build

The CLI will use ~/.river as the default state directory, but you can override with --state-dir.

State Directory Structure#

The CLI creates and manages:

~/.river/
├── users/           # JSON files containing user data
│   ├── alice.json   # User configuration and feed list
│   └── bob.json
└── feeds/
    └── user/        # Aggregated Atom feeds
        ├── alice.xml # All posts from alice's feeds
        └── bob.xml

User Management#

Add a new user#

river-cli user add alice --name "Alice Smith" --email "alice@example.com"

List all users#

river-cli user list

Show user details#

river-cli user show alice

Remove a user#

river-cli user remove alice

Feed Management#

Add a feed to a user#

river-cli user add-feed alice --name "Alice's Blog" --url "https://alice.example.com/feed.xml"
river-cli user add-feed alice --name "Tech News" --url "https://technews.example.com/rss"

Remove a feed from a user#

river-cli user remove-feed alice --url "https://alice.example.com/feed.xml"

Synchronization#

Sync feeds for a specific user#

river-cli sync alice

Sync all users#

river-cli sync

Sync with different log levels#

# Info level (default shows main operations)
river-cli sync alice --verbosity=info

# Debug level (shows detailed HTTP and parsing logs)
river-cli sync alice --verbosity=debug

# Quiet mode (no logs)
river-cli sync alice --quiet

Example Workflow#

1. Setup users and feeds:

# Add a user
river-cli user add alice --name "Alice Smith" --email "alice@example.com"

# Add some feeds
river-cli user add-feed alice --name "Alice's Blog" --url "https://alice.example.com/feed.xml"
river-cli user add-feed alice --name "HackerNews" --url "https://hnrss.org/frontpage"

# View the configuration
river-cli user show alice

2. Initial sync:

river-cli sync alice --verbosity=debug

3. Check the result: The aggregated feed will be saved to ~/.river/feeds/user/alice.xml and contains all posts from both feeds, deduplicated and sorted by date.

4. Regular sync:

# Run periodically (e.g., via cron)
river-cli sync alice

Using Custom State Directory#

# Use a custom directory
river-cli --state-dir ./my-feeds user add alice --name "Alice" --email "alice@example.com"
river-cli --state-dir ./my-feeds user add-feed alice --name "Feed" --url "https://example.com/feed.xml"
river-cli --state-dir ./my-feeds sync alice

JSON User File Format#

User files (e.g., ~/.river/users/alice.json) contain:

{
  "username": "alice",
  "fullname": "Alice Smith",
  "email": "alice@example.com",
  "feeds": [
    {
      "name": "Alice's Blog",
      "url": "https://alice.example.com/feed.xml"
    },
    {
      "name": "HackerNews",
      "url": "https://hnrss.org/frontpage"
    }
  ],
  "last_synced": "2025-09-29T14:30:00Z"
}

Logging#

The CLI uses structured logging with multiple levels:

• Debug: Detailed HTTP requests, TLS info, feed parsing details
• Info: Main operations (fetching feeds, creating users, sync progress)
• Warning: Recoverable issues
• Error: Failures and exceptions
• Quiet: No output

Logging Options#

# Specific log level
--verbosity=debug|info|warning|error|quiet

# Short flags
-v, --verbose    # Increase verbosity (repeatable)
-q, --quiet      # Quiet mode

# Color control
--color=auto|always|never

Example with different log levels#

# See all details including HTTP requests and parsing
river-cli sync alice --verbosity=debug

# See main operations only
river-cli sync alice --verbosity=info

# Completely silent
river-cli sync alice --quiet

Features#

• Deduplication: Posts with same ID are not duplicated
• Sorting: Posts are sorted by date (newest first)
• Error handling: Failed feeds don't stop sync of other feeds
• Structured logging: Uses Logs library with fmt and logs.cli integration
• Feed formats: Supports both Atom and RSS2 feeds
• State persistence: User configuration and aggregated feeds are saved locally