freshrss-cli

README

freshrss-cli

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

Installation

Homebrew

brew tap roboalchemist/tap
brew install freshrss-cli

From source

git clone https://github.com/roboalchemist/freshrss-cli.git
cd freshrss-cli
make build
sudo make install

Authentication

FreshRSS uses an API password (separate from your login password). Set it in FreshRSS under Settings > Profile > API password.

Interactive setup

freshrss auth

With flags

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

Environment variables

export FRESHRSS_URL=https://freshrss.example.com
export FRESHRSS_USER=alice
export FRESHRSS_PASSWORD=api-pass

Credentials are stored in ~/.freshrss-auth.json (mode 0600). Environment variables take priority over the config file.

Usage

Feeds

freshrss feeds list                              # List all feeds
freshrss feeds add https://example.com/feed.xml  # Subscribe
freshrss feeds add URL -t "Custom Name" -c Tech  # With title & category
freshrss feeds remove feed/123                   # Unsubscribe
freshrss feeds update feed/123 -t "New Title"    # Edit metadata

Articles

freshrss articles list                   # Unread articles (default)
freshrss articles list --starred         # Starred only
freshrss articles list -f feed/123       # Filter by feed
freshrss articles list -c Technology     # Filter by category
freshrss articles list --all -n 50       # All articles, limit 50
freshrss articles search "golang"        # Search
freshrss articles view <item-id>         # Read article content
freshrss articles view <id> --raw        # Raw HTML output
freshrss articles read <item-id>         # Mark as read
freshrss articles unread <item-id>       # Mark as unread
freshrss articles star <item-id>         # Star article
freshrss articles unstar <item-id>       # Remove star

Categories

freshrss categories list

Status

freshrss status    # Unread counts per feed

Bulk Mark Read

freshrss mark-read --feed feed/123       # Mark entire feed
freshrss mark-read --category Tech       # Mark entire category
freshrss mark-read --all                 # Mark everything
freshrss mark-read --all --before 1700000000  # Before timestamp

Output Formats

freshrss feeds list                          # Table (default, colored)
freshrss feeds list --json                   # JSON
freshrss feeds list --plaintext              # Tab-separated for piping
freshrss feeds list --json --fields title,url  # Filter JSON fields
freshrss feeds list --json --jq '.subscriptions[0]'  # JQ filtering
freshrss feeds list --no-color               # Disable colors

Shell Completion

# Bash
source <(freshrss completion bash)

# Zsh
source <(freshrss completion zsh)

# Fish
freshrss completion fish | source

Claude Code Skill

freshrss skill print    # View embedded skill
freshrss skill add      # Install to ~/.claude/skills/freshrss-cli/

License

MIT