AgentSkillsCN

Skill

技能

SKILL.md

freshrss-cli

CLI tool for managing FreshRSS feeds, articles, and categories via the Google Reader compatible API.

Quick Start

bash
# Authenticate
freshrss auth --url https://freshrss.example.com --user alice --password api-pass

# Or use environment variables
export FRESHRSS_URL=https://freshrss.example.com
export FRESHRSS_USER=alice
export FRESHRSS_PASSWORD=api-pass

Common Operations

bash
# Feeds
freshrss feeds list                           # List all feeds
freshrss feeds add https://example.com/rss    # Subscribe
freshrss feeds add URL -c Technology          # Subscribe to category
freshrss feeds remove feed/123                # Unsubscribe

# Articles
freshrss articles list                        # Unread articles
freshrss articles list --starred              # Starred only
freshrss articles list -f feed/123 -n 10      # Filter by feed
freshrss articles search "keyword"            # Search
freshrss articles view <item-id>              # Read article
freshrss articles read <item-id>              # Mark as read
freshrss articles star <item-id>              # Star article

# Status & Bulk
freshrss status                               # Unread counts
freshrss mark-read --feed feed/123            # Mark feed as read
freshrss mark-read --all                      # Mark everything read

# Categories
freshrss categories list                      # List categories

Output Formats

bash
freshrss feeds list                    # Table (default)
freshrss feeds list --json             # JSON
freshrss feeds list --plaintext        # Tab-separated
freshrss feeds list --json --fields title,url  # Filter fields
freshrss feeds list --json --jq '.subscriptions[0].title'

Auth Priority

  1. •Environment variables: FRESHRSS_URL, FRESHRSS_USER, FRESHRSS_PASSWORD
  2. •Config file: ~/.freshrss-auth.json

Gotchas

  • •URL must be the root, not the web UI path. Use https://freshrss.example.com, NOT https://freshrss.example.com/i/index.php.
  • •FreshRSS has separate web login and API passwords. The API password is set in FreshRSS settings under "Profile > API management".
  • •Article IDs are long tag URIs. Format: tag:google.com,2005:reader/item/00064ae1dd59223f. Always quote them in shell commands.
  • •--fields filters the top-level JSON. The wrapper key (e.g. subscriptions) is removed — output becomes a flat array.
  • •articles search returns "No results found." (not JSON) when empty. Check for this string before parsing JSON output.
  • •mark-read --all has no undo. There's no bulk mark-unread. Use --feed or --category scoping in automation.

Reference

See reference/commands.md for full command reference.