NOSS(1p)

NAME
noss - RSS/Atom feed reader and aggregator

SYNOPSIS
noss command syntax:

  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
  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

  -h|--help      Print usage message
  -v|--version   Print version and copyright information

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

noss works by storing feed and post information in a local database, and the user interacts with the database by supplying commands to noss.

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 subequent "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.

  # 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.

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.

"include_title": "target" | [ "target", ... ]
"exclude_title": "target" | [ "target", ... ]
    Specify a target string or list of target strings a post title must include or 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 include/exclude, or a Perl regex (signified by a leading and trailing forward slash character) that a title must match/not match.

"include_content": "target" | [ "target", ... ]
"exclude_content": "target" | [ "target", ... ]
    Similar to the "include_title" and "exclude_title" parameters, except for a post's content instead of its title.

"include_tags": "tag" | [ "tag", ... ]
"exclude_tags": "tag" | [ "tag", ... ]
    Specify a tag or list of tags that a post must be tagged with or 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.

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.

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.

default

The "default" field is a special feed group that every feed is a part of. Any configuration in the "default" feed will 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

  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.

    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 are 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. fmt is a string that consists of formatting codes which will be substituted by noss for whatever information the code represents. A formatting code starts with a percentage sign, followed by an optional integar specifying the pad width, and a character signifying what the code is actually formatting. If the pad width is negative, the text will be left-justified. See also the "read_format" configuration option.

    The format string can use the following formatting codes:

    %%  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 signifying the post's read status ("r" for read, "U" for unread).

    %S  The post's read status, "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 "time_format" configuration field.

--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. This option works just like the "--read-format" option in the "read" command. Consult its documentation for how formatting works and list of valid formatting codes.

  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. Consult the documentation for the read command's "--read-format" option for information on how formatting works and a list of valid formatting codes.

  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. Consult the documentation for the read command's "--read-format" option for information on how format strings are processed.

    The following format codes are available:

    %%  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.

  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.

  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 no 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
These options can be used with any command.

-c|--config=file
    Specify path to the noss configuration file.

-D|--data=dir
    Specify path to the noss data directory. The data directory is the directory where noss stores data like its feed database and feed cache.

-f|--feeds=file
    Specify path to the noss feeds file.

-A|--autoclean[=0|1]
    Toggle whether noss should automatically run the "clean" command after any operation. 0 disables autoclean, 1 enables it. Giving no argument is the equivalent to enabling autoclean. This command helps with automatically freeing up unused space at the cost of a slight performance penalty. By default, autoclean is disabled. This option can also be configured via the "autoclean" configuration field.

-z|--time-format=fmt
    Specify the time format to use for the %z formatting code. strftime(3) is used to perform the time formatting, so consult its manual for writing a format string. See also the "time_format" configuration field.

    %z is the default formatting code used by the "feed" and "post" commands, so this option will also affect their output.

    If this option is not set, %z will default to the %c strftime(3) formatting code.

-h|--help
    Print noss's usage message and exit.

-v|--version
    Print noss's version and copyright info, then exit.

CONFIGURATION
noss can have its behavior configured by writing it a configuration file. A noss configuration file is a JSON file that supports the same extensions as the feeds file (comments and trailing commas).

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

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 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
    Number of parallel downloads to perform when fetching feeds for the "update" command. See also the "update" command's "--downloads" option.

"limit_rate": "speed"
    The maximum transfer rate for downloads. speed follows the same format as the speed given to the "--limit-rate" option.

"user_agent": "agent"
    The string to use as 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 one used in the "update" command's "--proxy" option.

"proxy_user": "user:password"
    The username and password to use for proxy authentication. Follows the same format as the one used in the "update" command's "--proxy-user" option.

"pager": "command"
    The command to use for reading posts via the "read" command. See also the "read" command's "--pager" option.

"browser": "command"
    The command to use for opening URLs.

"sort": "method"
    How you would 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
    Limit the number of posts that are listed with the "list" command. If limit is less than or equal to 0, there is no limit. See also the "list" command's "--list-limit" option.

"line_width": width
    The line width to use for the formatted text output of the "read" command. See also the "read" command's "--width" option.

"read_format": "fmt"
    The format to use for the HTML contents of a post that noss will format for the "read" command. See the documentation for the "read" command's "--read-format" option for more information on the details of how text formatting works.

"list_format": "fmt"
    The format to use for posts in the "list" command. See also the "list" command's "--list-format" option.

"post_format": "fmt"
    The format to use for the post information printed in the "post" command. See also the "post" command's "--post-format" option.

"feeds_format": "fmt"
    The format to use for feed information printed in the "feeds" command. See also the "feeds" command's "--feeds-format" option.

"autoclean": bool
    Boolean determining whether noss should automatically run the "clean" command after performing any operation. See also the "--autoclean" option.

"time_format": "fmt"
    The strftime(3) format string to use for formatting %z times. See also the "--time-format" option.

NOSSUI
For Unix-like systems, noss also comes with a script called nossui(1), which is a dialog(1)-based frontend that provides a terminal user interface for noss. Not all of the functionality of noss is available through nossui(1), so it shouldn't be used as a complete replacement for noss, but it should be suitable for most of noss's routine usage.

ENVIRONMENT

NOSS_DATA
    Directory for noss to store program data in.

NOSS_CONFIG
    Path to noss's configuration file.

NOSS_FEEDS
    Path to noss's feeds file.

XDG_DATA_HOME
    Directory for noss to store its data directory in, if no data directory path is configured otherwise.

XDG_CONFIG_HOME
    Directory where noss looks for configuration in by default.

PAGER
    Default pager to use for the "read" command.

BROWSER
    Default browser to use for opening URLs.

CAVEATS
Updating a feed too frequently can be wasteful on a server's resources, and in extreme cases could result in them banning you from accessing their feed. The acceptable frequency of feed updates varies from server to server, but a good rule of thumb is once per hour at most. You should also refrain from using the "--unconditional" option without a good reason.

AUTHOR
Written by Samuel Young, <samyoung12788@gmail.com>.

This project's source can be found on its Codeberg page <https://codeberg.org/1-1sam/noss.git>. Comments and pull requests are welcome!

COPYRIGHT
Copyright (C) 2025 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
nossui(1), curl(1), less(1), lynx(1), more(1), sqlite3(1), strftime(3)