photon(1)

📦 version 1.0.1, in alpine 3.24

🌸 photon(1) — General Commands Manual 🌸

okay bestie, so this is the man page for photon, and yes it's filed under General Commands Manual, and yes we're gonna get into it 💅

✨ NAME ✨

photon — an RSS reader as light as a photon, with terminal + sixel support 🦋 (yes, that light. literally the lightest.)

✨ SYNOPSIS ✨

photon [OPTION] [<paths> ...]

✨ DESCRIPTION ✨

so photon is an RSS/Atom reader and its whole vibe is speed, usability, and a lil sprinkle of unix philosophy ✨ It shows you your items in a card grid with exactly one card selected (main character energy 👑), and then you scroll around, read the article, play media, or open stuff in your default app.

and when you wanna extend it? lua plugins, babe. 🧚 photon can also dynamically load opencl for image scaling — no cap, it do be like that 🔥

✨ OPTIONS ✨

  • [<paths> ...] — RSS/Atom urls, a config path, or - for stdin. (yes, - means "feed me from the pipe" 🍓)
  • -h, --help — shows the context-sensitive help. 🫶
  • --extractor — the command for media link extraction; the item link gets substituted for %. env: PHOTON_EXTRACTOR Default: yt-dlp --get-url %
  • --video-cmd — set the default command for opening the item's media link in a video player. The media link gets substituted for %, and a direct item link gets substituted for $. If you provide neither % nor $, photon will download the data and pipe it to the command's stdin 😭 env: PHOTON_VIDEOCMD Default: mpv $
  • --image-cmd — set the default command for opening the item's media link in an image viewer. The media link gets substituted for %, and a direct item link gets substituted for $. If you provide neither % nor $, photon will download the data and pipe it to the command's stdin 🌸 env: PHOTON_IMAGECMD Default: imv -
  • --torrent-cmd — set the default command for opening the item's media link in a torrent downloader. The media link gets substituted for %. If the link is a torrent file, photon will download it, and substitute the torrent file path for % 🔥 env: PHOTON_TORRENTCMD Default: mpv %
  • --article-mode — the default article view mode. env: PHOTON_ARTICLE_MODE Default: ARTICLE
  • --article-renderer — the command to render item.Content/item.Description. env: PHOTON_ARTICLE_RENDERER Default: w3m -T text/html -dump -cols 72
  • -b, --cookie=KEY=VALUE;... — sets the cookie for all outgoing http requests 🍪
  • -H, --header=KEY=VALUE;... — sets the headers for all outgoing http requests
  • -A, --user-agent — sets the User-Agent header for all outgoing http requests
  • -k, --insecure — (TLS) by default, every SSL connection photon makes is verified to be secure. This option lets photon proceed and operate even for server connections that would otherwise be considered insecure ⚠️ like, careful babe.
  • --download-path — the default download path. Default: $HOME/Downloads
  • -t, --terminal-title — set the terminal title ✨
  • -r, --refresh=SECONDS — refresh interval in seconds. env: PHOTON_REFRESH Default: 0 (which means it doesn't automatically refresh)

✨ USAGE ✨

🎀 GENERAL

so photon's whole philosophy is to be some kind of rss viewer. Which means — plot twist — it does not have features like adding or managing feeds. 🙈 Feed management is a you problem, bestie. But! You can start photon with a list of urls:

$ photon https://static.fsf.org/fsforg/rss/news.xml
https://itsfoss.com/feed/
https://blog.golang.org/feed.atom?format=xml

or you can feed it the feed data directly:

$ curl -s https://www.reddit.com/r/pics.rss | photon -

or use ratt and play magnet links directly with mpv:

$ ratt auto https://1337x.to/top-100 | photon -

or search youtube using ratt(1):

$ ratt auto https://www.youtube.com/results --data-
urlencode="search_query=MyQuery" | photon -

or it can parse a config file (peep photon(5)):

$ cat mychannels.txt
#youtube - LunusTechTips
https://www.youtube.com/feeds/videos.xml?user=LinusTechTips
#youtube - Rob Braxman Tech
https://www.youtube.com/feeds/videos.xml?channel_id=UCYVU6rModlGxvJbszCclGGw
#odysee - Lunduke on Tech" > mychannels.txt
https://lbryfeed.melroy.org/channel/odysee/@Lunduke:e
$ photon mychannels.txt

or it can call an external command — you gotta specify it with the cmd:// prefix:

$ echo "cmd://ratt auto https://videoportal.joj.sk/slovania" >> mychannels.txt
$ photon mychannels.txt

and by default, running photon with no arguments will try to read ~/.config/photon/config 👀

so yeah — feed management is entirely up to you, with arguments, text files, and scripts like:

$ cat photon-reddit.sh
photon mysubreddits.conf
$ cat mysubreddits.conf
https://www.reddit.com/r/popular.rss
https://www.reddit.com/r/news.rss
https://www.reddit.com/r/funny.rss
https://www.reddit.com/r/memes.rss

🎀 ARTICLE VIEW

press ENTER and photon hits you with the article view, where it scraps the card's link and extracts the title, top image, and main text content ✨ The article view also has three modes:

  • ARTICLE — shows the scrapped article content
  • DESCRIPTION — shows the item.Description
  • CONTENT — shows the item.Content

article view in DESCRIPTION or CONTENT mode can use an external tool to render the text. By default w3m is used, but you can change that with the --article-renderer argument, or the PHOTON_ARTICLE_RENDERER environment variable 💅

OSC8 links are supported, so every link in an article can be opened with the terminal without needing to select the url — and article view can show just the text of the link and not the url. iconic 🎀

🎀 MEDIA EXTRACTION

photon can extract the direct media link of the rss item 🔥 Media extraction is done by yt-dlp by default. Based on the content type of the media, photon will run it in either a video player (default mpv) or an image viewer (default imv). And if the link is a magnet link, or a torrent file, photon will run it in a torrent downloader/player (default mpv with the webtorrent-mpv-hook script) — yes, the whole setup, slay 💅

✨ KEYBINDINGS ✨

🎀 CARD VIEW

  • h — move selected card to the left
  • j — move selected card down
  • k — move selected card up
  • l — move selected card to the right
  • CTRL+- — will decrease the number of columns of cards.
  • CTRL+= — will increase the number of columns of cards.
  • ENTER — will show the article view
  • p — will play the media link
  • r — refresh feeds
  • o — will open the card's link in the default web browser (or default application).
  • yy — copy card link to clipboard
  • dm — download media
  • dl — download link content
  • di — download image
  • CTRL+d — scroll half screen down
  • CTRL+u — scroll half screen up
  • CTRL+f — scroll full screen down
  • CTRL+b — scroll full screen up
  • gg — go to the first line
  • G — go to the last line
  • q — exit the application

🎀 ARTICLE VIEW

  • m — circle trough article view mode
  • yy — copy article link
  • o — open article in the browser
  • j — scroll the article down
  • k — scroll the article up
  • CTRL+d — scroll half screen down
  • CTRL+u — scroll half screen up
  • CTRL+f — scroll full screen down
  • CTRL+b — scroll full screen up
  • gg — scroll the article to the top
  • G — scroll the article to the bottom.
  • q or Esc — close the article.
  • The standard view of urls of your terminal can be also used (CTRL+SHIFT+U) 🫶

searching is done by pressing / and then typing the query. photon will filter the visible cards by finding the query in either the card's title, description, or feed's title 🔍✨

✨ LUA PLUGINS ✨

photon will automatically load lua scripts from ~/.config/photon/plugins/*.lua 🧚

these plugins help extend the functionality and make photon do whatever the user needs. Lua plugins can subscribe for events or register new keybindings and modify the state 💜 To see the entire photon lua plugins tutorial please see photon-lua(7)

✨ SEE ALSO ✨

photon(5), photon-lua(7)

✨ AUTHORS ✨

maintained by Vladimír Magyar <vladimir@mgyar.me> 🫶 Up-to-date sources can be found at https://sr.ht/~ghost08/photon and bugs/patches can be submitted by email to ~ghost08/photon@todo.sr.ht

okay that's the whole thing!! 🎀 this page is from 2026-10-14 and it's the photon(1) page from the General Commands Manual — go forth and read your feeds, bestie, you're literally gonna slay 💅✨🌈

📦 where this page comes from