NOSS(1)

📦
version 2.02 · 2 versions
, in alpine 3.24

💖 NOSS(1) 💖

from the User Contributed Perl Documentation collection

okay so this is the manual for the one and only noss, and we're gonna walk through it together. no cap. 🦋

🌸 NAME 🌸

noss — RSS/Atom feed reader and aggregator. That's the whole vibe: feeds, posts, main character energy. 💅

✨ SYNOPSIS ✨

The page says noss command syntax:, and the actual shape is this:

noss <command> [options] [arguments]

Commands 🎀

  • update — Fetch and reload feeds
  • reload — Reload cached feeds
  • read — Read post in pager
  • open — Open feed or post URL in browser
  • cat — Print post to stdout
  • list — List and filter posts
  • unread — List unread posts
  • mark — Mark posts as read or unread
  • post — View post information
  • feeds — List feeds
  • groups — List feed groups
  • clean — Clean up obsolete files and data
  • discover — Discover feed URLs associated with a web page
  • export — Export feed list as OPML
  • import — Import feed list from OPML
  • help — View documentation for a noss command

Global options 🌈

  • -c|--config=<file> — Specify path to configuration file
  • -D|--data=<dir> — Specify path to data directory
  • -f|--feeds=<file> — Specify path to feeds file
  • -z|--time-format=<fmt> — Specify default strftime format for time strings
  • -a|--autoclean[=1|0] — Toggle autoclean
  • -C|--color[=1|0] — Toggle colored output
  • --no-color — the --no-color flag is listed right here, with no extra description attached
  • -h|--help — Print usage message
  • -v|--version — Print version and copyright information

✨ DESCRIPTION ✨

Okay so bestie, noss is a command-line program for aggregating and reading RSS/Atom feeds. It can fetch feed updates, list posts, read posts from the command-line, open posts in a browser, and literally so much more. 💖

noss works by storing feed and post information in a local database, and you interact with that database by supplying commands to noss. Very main character energy, tbh.

noss requires a feed list in order for it to function. A feed list is supplied to noss via a feeds file — a file that contains a list of feeds and any special configuration to use for those feeds. The format of this file is documented in the subsequent Feeds File section of this manual. Once a list of feeds is supplied to noss through the feeds file, the feeds can then be fetched and loaded into its database via the update command. 🫶

In order for noss to read posts, it must be able to uniquely identify and distinguish posts from each other. Posts in noss are identified via two pieces of information: the name of the feed they're in and their unique ID within that feed. When reading a post, like with either the read or open command, you would typically supply the command with the feed name and post ID to refer to that specific post.

# Read post #1 in the PlanetDebian feed
noss read PlanetDebian 1

To determine the feed and ID of a post, the list command can be used to query the post database for a list of posts that conform to whatever search parameters are provided (like title containing a string, content matching a regex, being tagged with a specific tag, etc.). The post command can also be used to query more detailed post information than the list command provides for a specific post. Consult the documentation for the list and post commands in the COMMANDS section of this manual. 📚

So basically, the typical usage of noss would involve managing your feed list from the feeds file, using the update command to fetch feed updates, using the list command to see what posts are available, and then using read or open commands for actually reading posts. It’s giving “organized little feed gremlin” and we love that.

# Add your feeds
vim ~/.config/noss/noss.feeds

# Fetch and update feed updates
noss update

# Look to see what posts you have
noss list
# ...or only check for unread ones
noss unread

# And then actually reading a post
noss read whatever 12

The COMMANDS section of this manual documents the complete list of commands and any options that are available to them.

noss can also have its behavior modified through a configuration file, whose format is documented in the CONFIGURATION section of this manual. ✨

🎀 Feeds File 🎀

As previously mentioned, noss reads its feed list from a feeds file. The feeds file is a JSON file that contains a list of feeds, feed groups, and feed configurations for noss to use. noss uses a special JSON format that supports comments and trailing commas, so that it can be better suited as a configuration file format. Comments start with a hash (#) sign, are terminated by the end of a line, and can be placed anywhere where JSON allows whitespace. 💅

noss will look for a feeds file in the following locations:

  • Path specified by the "-f"|"--feeds" option
  • $NOSS_FEEDS
  • $XDG_CONFIG_HOME/noss/noss.feeds
  • $XDG_CONFIG_HOME/noss.feeds
  • ~/.config/noss/noss.feeds
  • ~/.config/noss.feeds
  • ~/.noss.feeds

The feeds file can have three different fields: feeds, groups, and default. The only required field is the feeds field. No cap.

🌱 feeds 🌱

The feeds field is a key-value map of feed names and their configuration. Feed names can only contain alphanumeric/underscore characters, and must not be the name of another feed or group. The feed can either be mapped to a URL string of the feed it represents or a key-value map of configuration parameters for the feed. The former has the benefit of better readability but lacks the ability to have its configuration fine-tuned. The latter can have fine-tuned configuration but may look more cluttered than the former.

{
  "feeds": {
    # Just the URL, no specific configuration
    "feed1": "https://phonysite.com/feed1.rss",
    # Key-value map allows for fine-tuned configuration
    "feed2": {
      "feed": "https://phonysite.com/feed2.rss",
      "limit": 100,
      "autoread": false,
    },
  }, # yes, you can have trailing commas :-)
# yes, you can have comments, too!
}

When using the latter-style key-value map syntax for a feed, the only required field is the feed field, which must store the feed's URL. Additional fields, which are listed below, can be set to provide the previously mentioned fine-tuned configuration. 🌸

  • "limit": integar — specify a limit to the number of posts a feed can contain. If a feed exceeds the limit, noss will discard older posts to fit into that limit. By default, there is no limit to the number of posts a feed can contain.
  • "respect_skip": bool — specify whether to respect the skipDays and skipHours fields in RSS feeds, which tells feed aggregators to skip updating feeds on certain hours or days. This is enabled by default, and is recommended to not be disabled. > Bestie, please leave this one enabled unless you have a very good reason.
  • "include_title": "target" | [ "target", ... ] — specify a target string or list of target strings a post title must include in order to not be filtered out by noss during aggregation. A target string can either be a literal string that a post title must include, or a Perl regex (signified by a leading and trailing forward slash character) that a title must match.
  • "exclude_title": "target" | [ "target", ... ] — specify a target string or list of target strings a post title must not include in order to not be filtered out by noss during aggregation. A target string can either be a literal string that a post title must exclude, or a Perl regex (signified by a leading and trailing forward slash character) that a title must not match.
  • "include_content": "target" | [ "target", ... ] — similar to the include_title and exclude_title parameters, except for a post's content instead of its title. A target string or list of target strings a post's content must include in order to not be filtered out during aggregation; literal strings and Perl regexes are both allowed, with a regex signified by a leading and trailing forward slash character.
  • "exclude_content": "target" | [ "target", ... ] — same idea as the content-include situation, but for content that must not include/not match the target in order to not be filtered out during aggregation. Again, literal strings and Perl regexes are both allowed, with a regex signified by a leading and trailing forward slash character.
  • "include_tags": "tag" | [ "tag", ... ] — specify a tag or list of tags that a post must be tagged with in order to not be filtered out by noss during aggregation.
  • "exclude_tags": "tag" | [ "tag", ... ] — specify a tag or list of tags that a post must be tagged without in order to not be filtered out by noss during aggregation.
  • "autoread": bool — specify whether new posts from this feed should automatically be marked as read or not. Defaults to false.
  • "default_update": bool — specify whether this feed should be included in a default update or not (update when ran with no arguments). Defaults to true.
  • "hidden": bool — specify whether this feed should be omitted from the list command's default listing (the list shown when ran with no arguments). Defaults to false.

A feed's specific configuration takes priority over the configuration it may inherit from the default field or any groups it may be a part of. Periodt. 👑

noss uses curl(1) for fetching feeds, so generally any URL that is acceptable for curl(1) will be acceptable for noss. There are two unique types of URLs that noss will process in a special way. 🦋

  • file:///path/to/file — a URL that starts with the file:// protocol will be interpreted as a local file which noss will copy over to its feed cache and load instead of fetching remotely via curl(1).
# Use the contents of "/home/sam/feeds/feed.rss" as a feed
"file_feed": "file:///home/sam/feeds/feed.rss"
  • shell://command — a URL that starts with the shell:// protocol will be interpreted as a shell command which noss will execute and capture the output of, then use that output as the contents of the feed.
# Use the output of the "cat feed.rss" command as a feed
"shell_feed": "shell://cat feed.rss"

🦋 groups 🦋

groups is a key-value map of group names and their configuration. Feed groups in noss serve two purposes: 1) to provide a way to logically group multiple feeds together, and 2) provide a way to “share” a common configuration between multiple different feeds. Iconic, honestly.

Just like with feeds, group names can only contain alphanumeric/underscore characters and cannot be the same name as any other group or feed. A group can either be defined by a list of feed names with no special configuration, purely acting as a logical collection of feeds, or a key-value map of feed configuration parameters with a feed list stored in the feeds field of the map. The same options listed above for a feed's configuration in the feeds field can be used for a group's configuration. ✨

{
  "groups": {
    # purely logical feed grouping, no special configuration
    "group1": [ "f1", "f2", "f3" ],
    # each feed will inherit group2's configuration
    "group2": {
      "feeds": [ "f2", "f4", "f6" ],
      "limit": 100,
      "autoread": false,
    },
  },
  "feeds": {
    ...
  },
}

Feeds are also allowed to be a part of multiple different groups. If a feed is a part of multiple different groups that try to configure the same parameter, noss will try to resolve the conflict by picking the most “non-default” option available. Group configurations take priority over the default field but are overridden by a feed's own configuration. The hierarchy is literally feed config > group config > default, and noss is doing its best to keep the peace. 💖

⭐ default ⭐

The default field is a special feed group that every feed is a part of. Any configuration in the default feed will be used by every feed and group (unless their configuration overrides the default's). The same configuration options available to a feed and group are available to default.

{
  # All feeds have a limit of 100 posts and must contain 'foo' in their
  # titles.
  "default": {
    "limit": 100,
    "include_title": [ "/foo/" ],
  },
  ..
}

✨ COMMANDS ✨

Okay bestie, this is the command center — every noss subcommand and every flag, no skips, no cap. 💅

💾 update 💾

noss update [feed|group] ...

Fetch and reload feeds. Whenever a new feed is added to noss's feed list, this command can be used to load it into noss's database.

If no specific feeds or groups are specified, all feeds are updated.

update has the following options:

  • --new-only — Only update feeds that are not present in the database.
  • --non-defaults — When running update with no arguments, update all feeds, even those that are configured to not be updated by default.
  • --downloads=num — Specify number of parallel downloads to perform. Default amount is 10. Can also be configured via the "downloads" configuration field.
  • --unconditional — Unconditionally download feeds, even if they have not been modified since the last update. This option should be used with caution, as performing unconditional downloads is wasteful on feed servers and considered bad practice.
  • --hard — Force noss to do a hard update on the updated feeds. A hard update means that noss will delete all of a feed's previous data prior to updating, meaning data like the read/unread status of a post are lost. This option implies --unconditional.
  • --limit-rate=speed — Specify the maximum transfer rate for downloads. Speeds are measured in bytes/second, unless a suffix is appended. "k"/"K", "m"/"M", and "g"/"G" correspond to kilobytes, megabytes, and gigabytes respectively. Can also be configured via the "limit_rate" configuration field.
  • --user-agent=agent — Specify the string to use as the user-agent string. Can also be configured via the "user_agent" configuration field.
  • --timeout=fractional second — Specify the maximum number of seconds a transfer is allowed to take. By default, the timeout is 45 seconds. This option can be set to 0 to disable the timeout. Can also be configured via the "timeout" configuration field.
  • --proxy=[protocol://]host[:port] — Specify the proxy server to use. If a protocol is not specified, defaults as a "http://" proxy. If no port number is specified, defaults to 1000. Can also be configured via the "proxy" configuration field.
  • --proxy-user=user:password — Specify the username and password to use for proxy authentication. Can also be configured via the "proxy_user" configuration field.

🔄 reload 🔄

noss reload [feed|group] ...

Reload cached feeds. Useful for when you make changes to a feed's configuration and want noss to recognize the changes. If no feeds are specified, reloads all cached feeds.

reload has the following options:

  • --hard — Forces noss to do a hard reload on the updated feeds. A hard reload means that noss will delete a feed's data prior to performing the reload, resulting in data like posts' read/unread statuses being lost.

📖 read 📖

noss read <feed> [post]

Read the specified post's contents from the specified feed via a pager. If no specific post is provided, the latest unread post in the feed is selected. A negative post ID can be specified to look for a post relative to end of the feed instead of the beginning.

read has the following options:

  • --pager=command — Use the specified command as the pager for reading the post's contents. Defaults to less(1) on Unix systems and more(1) on Windows systems. Can also be configured via the PAGER environment variable and "pager" configuration field.
  • --no-mark — Do not mark post as read.
  • --stdout — Instead of reading post via a pager, write the post's formatted contents to stdout.
  • --read-format=fmt — Specify the format for the post's HTML contents that noss will format when reading. See the FORMATTING section of this manual for information on how formatting works in noss. Also see the "read_format" configuration option.
  • --width=width — Specify the line width to use for the formatted text output. Defaults to 80. See also the "line_width" configuration field.
  • --html — Instead of reading the formatted contents of a post, read its unformatted HTML contents.

🐱 cat 🐱

noss cat <feed> [post]

Prints the specified post to stdout. This command is basically just an alias to read --stdout. If no post is specified, prints the latest unread post.

This command has the same options as the read command.

🌐 open 🌐

noss open <feed> <post>
noss open <feed>

Open the URL of the specified feed or post in a web browser. Like with the read and cat commands, a negative post ID can be specified to look for a post relative to the end of a feed.

open has the following options:

  • --browser=command — Use the specified command as the browser to use for opening the URL. Defaults to lynx(1). Can also be configured via the BROWSER environment variable and "browser" configuration field.
  • --no-mark — Do not mark post as read.

📋 list 📋

noss list [feed|group] ...

List posts from specified feeds. When listing posts, noss displays the post's read status, the name of the feed the post is a part of, the post's ID, and the title of the post. Each post is listed on a single line, which should make it easy to process in a pipeline.

If no feeds or groups are specified, all feeds are searched.

list has the following options:

  • --title=target — Only list posts containing the specified target string in their title. If the string starts and ends with a forward slash (/), list will interpret it as a Perl regex and search for posts whose titles match the given regex.
  • --tag=tag — Only list posts tagged with the specified tag. This option can be used multiple times to specify multiple different tags.
  • --status=status — Only list posts marked with the specified status. Valid values are "read" and "unread".
  • --content=target — Only list posts containing the specified target string in their HTML content. If the string starts and ends with a forward slash (/), list will interpret it as a Perl regex and search for posts that match the given regex. This option can be used multiple times to specify multiple different targets.
  • --sort=method — Sort post list by the given method. The following are valid methods:
    • date — Sort posts by date (default).
    • feed — Sort posts by feed.
    • title — Sort posts by title.

This option can also be configured via the "sort" configuration field.

  • --reverse — Print the post list in reverse order.
  • --list-limit=limit — Only list the first limit posts. When used with the --reverse option, shows the last limit posts. If limit is less than or equal to 0, there is no limit. By default, there is no limit. This option can also be configured via the "list_limit" configuration field.
  • --hidden — Show hidden feeds when using list with no arguments.
  • --list-format=fmt — Print post information using the specified format. See the FORMATTING section of this manual for information on how formatting in noss works. Also see the "list_format" and "list_unread_format" configuration fields.

📬 unread 📬

noss unread [feed|group] ...

Similar to the list command, except only shows unread posts.

This command has the same options as the list command.

✅ mark ✅

noss mark <status> <feed|group> [posts] ...
noss mark --all <status>

Mark the given posts in the specified feeds as "read" or "unread".

posts is a list of post IDs to mark as read. If a post argument is a range (from-to), then each post in that range is marked. posts can only be specified when marking posts in individual feeds, not when marking groups of feeds.

This command has the following options:

  • --all — Mark all posts in every feed as read or unread.

📝 post 📝

noss post <feed> <post>

View the post information for the specified post.

This command has the following options:

  • --post-format=fmt — Specify the format to use for printing post information. See the FORMATTING section of this manual for information on how formatting works in noss. Also see the "post_format" configuration field.

📡 feeds 📡

noss feeds [feed|group] ...

View feed information for specified feeds and/or groups. If no feeds are specified, prints information for all feeds.

This command has the following options:

  • --brief — Only print feed names, not additional feed info.
  • --feeds-format=fmt — Specify the format to use for printing feed information. See the FORMATTING section of this manual for information on how formatting works in noss. See also the "feeds_format" configuration field.

👯 groups 👯

noss groups [groups] ...

View group information. If no groups are specified, prints information for all groups.

This command has the following options:

  • --brief — Only print group names, not additional group info.

🧹 clean 🧹

noss clean

Cleans up obsolete cache files and database data.

This command has no unique options.

🔎 discover 🔎

noss discover <url>

Discover RSS/Atom feed URLs associated with the given web page URL, and print them out if found.

This command has the following options, which are the same as the update command's:

  • --limit-rate=speed — Same as the update option.
  • --user-agent=agent — Same as the update option.
  • --timeout=fractional second — Same as the update option.
  • --proxy=[protocol://]host[:port] — Same as the update option.
  • --proxy-user=user:password — Same as the update option.

📤 export 📤

noss export [opml]

Export feed list as an OPML file for transferring feed data to another feed reader. If no output file is specified, the OPML will be written directly to stdout.

This command has the following options:

  • --no-groups — Do not try to generate feed group structures in the exported OPML.
  • --export-special — By default, export does not export feeds that use special noss-specific URLs like shell:// or file:// feeds. This option disables that behavior.

📥 import 📥

noss import <opml> [json]

Import feed list from an OPML file. Will write the feed list as a JSON file which can be used by noss. Writes the feed file to json if specified, otherwise writes it directly to stdout.

This command has the following options:

  • --no-groups — Do not try to import feed groups from the OPML.

🆘 help 🆘

noss help [command]

Print documentation for the specified command. If no command is specified, the noss manual will be printed instead.

This command has no unique options.

💅 GLOBAL OPTIONS 💅

Okay bestie, these ones are the universal girlies — they work with any command. No cap.

  • -c, --config=file — tells noss exactly where your configuration file lives. Like giving it the address instead of letting it wander around looking for it.
  • -D, --data=dir — points noss at its data directory. That's the spot where noss keeps all its stuff — think the feed database and the feed cache. Very main character storage energy.
  • -f, --feeds=file — sets the path to the noss feeds file. Simple as that.
  • -A, --autoclean[=0|1] — toggles whether noss should automatically run the clean command after any operation. 0 turns autoclean off, 1 turns it on, and giving it no argument at all is the same as enabling it. It's literally the "free up unused space for me automatically" button, at the cost of a slight performance penalty. By default autoclean is disabled. You can also set this through the "autoclean" configuration field. 🧹✨
  • -z, --time-format=fmt — sets the time format used for the %z formatting code. strftime(3) does the actual formatting work, so go read its manual when you're writing a format string. See also the "time_format" configuration field. And heads up: %z is the default formatting code used by the feed and post commands, so this option quietly affects their output too. If you don't set this option, %z defaults to the %c strftime(3) formatting code. 🕰️
  • -C, --color[=0|1], --no-color — toggles colored output. 0 and --no-color disable color, 1 enables it. By default, color is enabled unless standard output is not a terminal — noss can tell, she's perceptive like that. 🌈
  • -h, --help — prints noss's usage message and dips. 🫶
  • -v, --version — prints noss's version and copyright info, then exits. Iconic.

🎀 CONFIGURATION 🎀

noss lets you configure her whole personality by writing her a configuration file. A noss configuration file is a JSON file, and it supports the same extensions as the feeds file — that means comments and trailing commas. Yes bestie, you can leave that trailing comma. She won't judge. 💖

Here's where noss goes looking for a configuration file, in order:

  • Path specified by the -c/--config option
  • $NOSS_CONFIG
  • $XDG_CONFIG_HOME/noss/noss.conf
  • $XDG_CONFIG_HOME/noss.conf
  • ~/.config/noss/noss.conf
  • ~/.config/noss.conf
  • ~/.noss.conf

A noss configuration file can contain the following fields:

  • "feeds": "path" — path to the feeds file. See also the -f/--feeds option.
  • "data": "dir" — path to use for the data directory. See also the -D/--data option.
  • "downloads": integar — how many parallel downloads to run when fetching feeds for the update command. See also the update command's --downloads option.
  • "limit_rate": "speed" — the maximum transfer rate for downloads. The speed follows the same format as the speed you'd give to the --limit-rate option.
  • "user_agent": "agent" — the string to use as the user-agent string for downloads. See also the update command's --user-agent option.
  • "timeout": fractional second — the maximum number of seconds a transfer is allowed to take. See also the update command's --timeout option.
  • "proxy": "[protocol://]host[:port]" — the proxy server to use for performing downloads. The proxy host string follows the same format as the one used in the update command's --proxy option.
  • "proxy_user": "user:password" — the username and password for proxy authentication. Follows the same format as the one used in the update command's --proxy-user option.
  • "pager": "command" — the command used for reading posts via the read command. See also the read command's --pager option.
  • "browser": "command" — the command used for opening URLs. 🦋
  • "sort": "method" — how you'd like the list command to sort posts. Valid methods are "date", "feed", and "title". See also the list command's --sort option.
  • "list_limit": limit — limits how many posts get listed with the list command. If limit is less than or equal to 0, there is no limit at all. See also the list command's --list-limit option.
  • "line_width": width — the line width used for the formatted text output of the read command. See also the read command's --width option.
  • "read_format": "fmt" — the format used for the HTML contents of a post that noss will format for the read command. Peep the docs for the read command's --read-format option for all the details on how text formatting actually works.
  • "list_format": "fmt" — the format used for posts in the list command. See also the list command's --list-format option.
  • "list_unread_format": "fmt" — the format used for unread posts in the list command. If this isn't set, the format from the "list_format" setting or the --list-format option gets used instead. 💅
  • "post_format": "fmt" — the format used for the post information printed in the post command. See also the post command's --post-format option.
  • "feeds_format": "fmt" — the format used for feed information printed in the feeds command. See also the feeds command's --feeds-format option.
  • "autoclean": bool — a boolean that decides whether noss automatically runs the clean command after performing any operation. See also the --autoclean option.
  • "time_format": "fmt" — the strftime(3) format string used for formatting %z times. See also the --time-format option.
  • "colors": { "code": "color", ... } — a key-value map of color codes (range 0-16) and their color names. The default color code values are documented down in FORMATTING/Default Color Codes. Consult the docs for Term::ANSIColor(3pm) for way more detail on how colors are handled in noss. 🎨
  • "colored_output": bool — toggles whether noss uses colored output or not. See also the --color option.

✨ FORMATTING ✨

Some noss commands let you customize how their output is formatted, and honestly? It's giving customized. Format strings are similar to C-style printf(3) strings — you use percentage-sign prefixed formatting codes, and each code gets substituted for the piece of data it represents. The percentage can also optionally be followed by an integar (positive or negative) that specifies the pad-width to use for that field. A positive pad-width justifies the field to the right, and a negative pad-width justifies it to the left. Left, right, she's flexible. 💁‍♀️

noss can also color her formatted output with color codes. A color code is a number in the range 0-16 enclosed in angle brackets, like "<...>". Each code maps to a different Term::ANSIColor(3pm) color, and you can configure those through the "colors" setting in noss's configuration file. And listen — if colored output is explicitly disabled, either with the --no-color option or with the "colored_output": false setting, then any color codes sitting in a format string just get ignored. Poof. Gone. 🙈

🌸 Post Formatting Codes 🌸

These codes work in the "read_format", "list_format", "list_unread_format", and "post_format" settings for the read, list, and post commands.

  • %% — a percentage sign.
  • %f — the name of the feed the post is in.
  • %i — the ID of the post.
  • %t — the title of the post.
  • %u — the URL of the post.
  • %a — the name of the author of the post.
  • %c — the list of categories the post is tagged under.
  • %s — a single character showing the post's read status ("r" for read, "U" for unread).
  • %S — the post's read status, spelled out as "read" or "unread".
  • %P — the HTML contents of the post.
  • %C — the date of the post in the preferred date/time representation of the current locale.
  • %d — the post's day of the month as a decimal number (range 01 to 31).
  • %w — the post's abbreviated day of the week according to the current locale.
  • %W — the post's full day of the week according to the current locale.
  • %m — the post's abbreviated month name according to the current locale.
  • %M — the post's full month name according to the current locale.
  • %n — the post's month as a decimal number (range 01 to 12).
  • %y — the post's year in two-digit form (range 00 to 99).
  • %Y — the post's full year.
  • %z — the post's time formatted according to the --time-format option or the "time_format" configuration field. ⭐

🦋 Feed Formatting Codes 🦋

These codes work in the "feed_format" setting for the feeds command.

  • %% — a percentage sign.
  • %f — the feed's name.
  • %l — the feed's link.
  • %t — the feed's title
  • %u — the feed's homepage.
  • %e — the feed's description.
  • %a — the feed's author.
  • %c — the feed's tags.
  • %p — the number of posts in the feed.
  • %r — the number of read posts in the feed.
  • %U — the number of unread posts in the feed.
  • %C, %d, %w, %W, %m, %M, %n, %y, %Y, %z — the same as their post formatting counterparts. 🫶

🎀 Default Color Codes 🎀

  • 0 — clear
  • 1 — black
  • 2 — red
  • 3 — green
  • 4 — yellow
  • 5 — blue
  • 6 — magenta
  • 7 — cyan
  • 8 — white
  • 9 — bold black
  • 10 — bold red
  • 11 — bold green
  • 12 — bold yellow
  • 13 — bold blue
  • 14 — bold magenta
  • 15 — bold cyan
  • 16 — bold white

🧚 NOSSUI 🧚

For Unix-like systems, noss also comes with a script called nossui(1), which is a dialog(1)-based frontend that gives noss a whole terminal user interface. Cute, right? But bestie, real talk: not all of noss's functionality is available through nossui(1), so it shouldn't be treated as a complete replacement for noss. It is suitable for most of noss's routine usage though, so for everyday vibes you're chilling. 💜

🌸 EXAMPLES 🌸

okay bestie, this is the part where it all clicks. real files, real commands, real vibes. you're gonna eat this up 💅

🎀 Feeds File 🎀

here's what your feeds file can look like when you're living your best life. note the comment at the top — that's not me being cute, that's the actual rule:

# Comments and trailing commas are allowed.
{
    "feeds": {
        "11sam": "https://1-1sam.codeberg.page/feed/atom.xml",
        "devault": "https://drewdevault.com/blog/index.xml",
        "AndrewKelley": "https://andrewkelley.me/rss.xml",
        "rachel": {
            "feed": "https://rachelbythebay.com/w/atom.xml",
            "default_update": false,
        },
        "lwn": {
            "feed": "https://lwn.net/headlines/Features",
            "exclude_title": "[$]",
        },
    },
    "groups": {
        "programming": [
            "11sam",
            "devault",
            "AndrewKelley",
            "rachel",
            "lwn",
        ],
        "news": {
            "feeds": [ "lwn" ],
            "limit": 10,
        },
    },
    "default": {
        "limit": 100,
    },
}

like, look at that. 11sam, devault, AndrewKelley and lwn are just plain strings — simple feed, simple entry. but rachel and lwn get the full object treatment so they can carry their own default_update and exclude_title settings. and the groups section? that's where you organize your little feed family into programming and news, with news getting its own limit of 10. then default sets a global limit of 100. iconic behavior honestly 🫶

💖 Configuration File 💖

and here's the config file. same deal, comments and trailing commas are allowed:

# Like with the feeds file, comments and trailing commas are allowed.
{
    "feeds": "~/feeds.json",
    "downloads": 10,
    "list_format": "%s %-16f %4i %t",
    "autoclean": true,
    "colors": {
        "3": "cyan",
        "7", "green",
        "11": "bold cyan",
        "15": "bold green",
    },
}

you got your feeds path pointing at ~/feeds.json, downloads set to 10, a custom list_format of "%s %-16f %4i %t", autoclean turned on, and a whole colors situation mapping color numbers to names like cyan, green, bold cyan and bold green. yes, that "7", "green", line is exactly what the page says — I'm not touching it, that's the manual's business, not mine 🙈

🦋 Basic Usage 🦋

okay this is the glow-up section. the whole journey, start to finish:

# Add feeds to your feeds file
$ mkdir -p ~/.config/noss
$ vim ~/.config/noss/noss.feeds
$ cat ~/.config/noss/noss.feeds
{
  "feeds": {
    "11sam": "https://1-1sam.codeberg.page/feed/atom.xml",
  },
}

# Pull feed updates
$ noss update
Fetched https://1-1sam.codeberg.page/feed/atom.xml
11sam: 7 new posts

# Browse posts
$ noss list
U 11sam 1 My (Inexperienced) Experience with CompTIA Certs
U 11sam 2 1st
U 11sam 3 Manuals for Raku Programs
U 11sam 4 New(ish) Site
U 11sam 5 quixftp
U 11sam 6 My site now has an Atom feed
U 11sam 7 LLM Poison

# Read posts...
# ...via pager
$ noss read 11sam 7
# ...or via browser
$ noss open 11sam 7

so you mkdir -p ~/.config/noss, you open ~/.config/noss/noss.feeds in vim, you cat it back to prove you did it, and boom — feed added. then noss update goes and fetches it, prints Fetched https://1-1sam.codeberg.page/feed/atom.xml, and tells you 11sam: 7 new posts. then noss list shows you all seven with those cute U markers, and you either noss read 11sam 7 in your pager or noss open 11sam 7 in your browser. literally the whole workflow in one screenshot. slay 🔥

🌈 ENVIRONMENT 🌈

the env vars, bestie. these are the little dials the outside world can turn:

  • NOSS_DATA — the directory where noss stores its program data. that's it, that's the vibe check.
  • NOSS_CONFIG — path to noss's configuration file. point it wherever you want.
  • NOSS_FEEDS — path to noss's feeds file. same energy, different file.
  • XDG_DATA_HOME — the directory noss puts its data directory in, but only if you haven't configured a data directory path some other way.
  • XDG_CONFIG_HOME — where noss looks for config by default. the default-default, if you will.
  • PAGER — the default pager used for the "read" command. your cozy little reading nook 🎀
  • BROWSER — the default browser used for opening URLs. for when you want the full experience.

💀 CAVEATS 💀

okay listen, this part matters, don't scroll past it:

updating a feed too frequently is wasteful on a server's resources, and in extreme cases it could get you banned from accessing their feed. not joking. the acceptable update frequency varies from server to server, but a good rule of thumb is once per hour at most.

and also — please, please don't use the --unconditional option unless you have a genuinely good reason. the manual says "refrain," and I'm saying it louder. respect the servers, they're doing their best 😭

👑 AUTHOR 👑

written by Samuel Young, <samyoung12788@gmail.com>.

the project's source lives on its Codeberg page at <https://codeberg.org/1-1sam/noss.git> — and guess what, comments and pull requests are welcome! so if you've got thoughts, send them. main character energy only 💜

Copyright (C) 2025-2026 Samuel Young

this program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. 📜

🧚 SEE ALSO 🧚

your little friends in the neighborhood, all here for you:

and that's the whole page, bestie, you made it to the end 🫶 this one's perl v5.42.2 energy, dated 2026-02-15, filed under NOSS(1) — go forth and read your feeds responsibly, mwah 💋✨

📦 where this page comes from