comitium(1)

# NAME

comitium - A feed aggregator for Gemini.

# SYNOPSIS

*comitium* <_COMMAND_> [_FLAGS_] [_ARGUMENTS_]

# DESCRIPTION

*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

# COMMANDS

*refresh* [_FLAGS_]
	Check for new updates to subscriptions and update aggregator page.

*list*
	List all subscriptions in a gemtext format suitable for remote bookmarking.

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

*remove* <_LINK_>
	Remove a subscription at _LINK_.

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

*version*
	Print version information.

# FLAGS

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

## GLOBAL FLAGS

*-d* _PATH_, *--data* _PATH_
	Set the data directory where *comitium* will store its files.

## ADD FLAGS

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

# ENVIRONMENT VARIABLES

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

# FILES AND DIRECTORIES

## DATA DIRECTORY

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

. If provided, the *-d*/*--data* flag
. If set, the $*COMITIUM_DATA* environment variable.
. If $*XDG_DATA_HOME* is set, then _$XDG_DATA_HOME/comitium_
. If $*HOME* is set and _$HOME/.local_ exists, then
  _$HOME/.local/share/comitium_
. If $*HOME* is set, then _$HOME/.comitium_
. Otherwise, the current working directory is used as a last resort

## FILES

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.

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

# EXAMPLES

This will add a new feed subscripton:
```
comitium add gemini://nytpu.com/gemlog/
```

This will add a new subscription over http:
```
comitium add -t a 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.

# SEE ALSO

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 docs at <https://git.nytpu.com/comitium/tree/doc/> or in
*docs/* in your local repository.

# AUTHOR

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.