aboutsummaryrefslogtreecommitdiffstats
comitium(1) General Commands Manual comitium(1)

comitium - A feed aggregator for Gemini.

comitium <COMMAND> [FLAGS] [ARGUMENTS]

comitium is tool to subscribe to feeds on the Gemini protocol. It supports a variety of feed formats:

•Gemini Feeds (https://gemini.circumlunar.space/docs/companion/subscription.gmi)
•Atom
•RSS
•JSON
•Watching pages for changes

refresh [FLAGS]

Check for new updates to subscriptions and update aggregator page.

regenerate

Will regenerate all the files created by comitium using cached entries without fetching any feeds.

add [FLAGS] <LINK> [TITLE]

Add a new subscription. LINK is a link to the feed or watched URL. TITLE is an optional title for the feed, otherwise a title will be automatically picked depending on the feed type. For Gemini feeds, the first heading on a page is used as a title. For ATOM, RSS, and JSON feeds, the provided title is used. For a page being watched for changes, the URL itself is used. Use -w to watch a page for changes. Also to note: when adding a new subscription, you do not need to run refresh afterwards, add will automatically fetch the entries and regenerate the .gmi and .json files.

remove [FLAGS] <LINK>

Remove a subscription at LINK. Will remove from both subscribed feeds and subscribed pages by default.

help

Print basic usage information, including a list of commands and flags with abbreviated descriptions.

version

Print version information.

Global flags are recognized for all commands. The subsections are for command-specific flags that are not universally recognized.

-d PATH, --data PATH

Set the data directory where comitium will store its files. See FILES AND DIRECTORIES for more information.

-l LANG, --lang LANG

The language that comitium will use when outputting its files. Can be a comma-separated list of language tags, comitium will use the first avalable. Overrides the $LANG environment variable. See <https://git.nytpu.com/comitium/about/doc/translating.md> for available options. Defaults to en-US.

-h DAYS, --history DAYS

The number of days of articles to display on feed.gmi. For instance, if it's set to 7 then only the past week of posts will be displayed or kept in comitium.json. Defaults to 31.

-n NUM, --num-workers NUM

Number of worker threads to use when refreshing feeds. More is faster, but there are more concurrent outgoing requests then, which can be not nice to the servers you're hitting and to other people on your network. Defaults to 5.

-t NUM, --timeout NUM

Set a timeout for requests, in seconds. Defaults to 10 seconds per request.

-w, --watch

Watch a page for changes instead of adding as a feed. Useful for gophermaps, or gemini/http resources with no parseable feed.

-f, --feeds

Remove the URL from subscribed feeds.

-p, --pages

Remove the URL from subscribed pages.

COMITIUM_DATA

Set the data directory. Equivalent to the --data flag.

COMITIUM_HISTORY

How many days should be included on feed.gmi. Equivalent to the --history flag.

LANG

Set the language comitium will output.

All files used by comitium are stored in the data directory. The data path is picked from the first available criterion in this list:

1.If provided, the -d/--data flag
2.If set, the $COMITIUM_DATA environment variable.
3.If $XDG_DATA_HOME is set, then $XDG_DATA_HOME/comitium
4.If $HOME is set and $HOME/.local exists, then $HOME/.local/share/comitium
5.If $HOME is set, then $HOME/.comitium
6.Otherwise, the current working directory is used as a last resort

Within the data directory, the following files are used:

comitium.json

A json file listing all of the feeds, their titles, their subscription type, and subscription-type-specific information. If you need to modify a subscription (change its title, update a link, etc) it should be trivial to manually edit.

header.gmi

This file is neither created nor modified by comitium. If it exists and is nonempty, then it is read and used as custom header for feed.gmi. If it doesn't exist or is empty, then a default header is used. The generated contents of feed.gmi will be appended to the contents of header.gmi separated by one newline.

footer.gmi

This file is neither created nor modified by comitium. If it exists and is nonempty, then it is read and used as a custom footer for feed.gmi and subscriptions.gmi. If it doesn't exist or is empty, then a default footer is used. Note the link "aggregated using comitium vX.X.X" will always be appended to ensure that all instances are compliant with the AGPL.

feed.gmi

The outputted text/gemini file containing the subscription items. Is what should be linked or copied to your server directory to publish it.

subscriptions.gmi

A text/gemini list of all the feeds being aggregated, suitable for remote bookmarking, etc. Should also be linked or copied to your server directory.

This will add a new feed subscripton:

comitium add gemini://nytpu.com/gemlog/

This will add a new subscription over http:

comitium add https://www.nytpu.com/files/atom.xml

This will add a new subscription to watch for changes:

comitium add --watch gemini://nytpu.com/photos/by-date.gmi "nytpu's photos"
Note that when watching a page for changes, you should manually add a title, otherwise the URL will be used.

This will update all feeds and regenerate subscriptions.gmi if you use a custom data directory:

comitium refresh -d ~/comitium-test
This also makes it possible to maintain multiple subscription "groups," for instance if you want to separate different topics into their own feeds.

For more information, see the README at <https://git.nytpu.com/comitium/about/> or in your local copy of the repository.

For a tutorial, see the quickstart at <https://git.nytpu.com/comitium/tree/doc/quickstart.md> or in docs/ in your local repository.

Maintained by nytpu <alex@nytpu.com>.

Source can be found at <https://git.nytpu.com/comitium>. Bugs & patches can be sent to ~nytpu/public-inbox@lists.sr.ht.

2021-12-04