.. Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.

=============
``moderator``
=============

Synopsis
========

A mailing list moderator tool used to manage mailing lists from the command line::


    usage: moderator [-h] [--debug] [--trace] [--log LOG] [--username USERNAME]
                     [--password PASSWORD] [--clear-store]
                     {list,add,lookup,remove} ...
    
    Mailing list moderator tool used to manage mailing lists from the command line.
    
    positional arguments:
      {list,add,lookup,remove}
    
    optional arguments:
      -h, --help           show this help message and exit
      --debug              Turn on debug mode / logging.
      --trace              Turn on trace logging. Implies --debug.
      --log LOG            Log file destination. Defaults to stdout only.
      --username USERNAME  Username
      --password PASSWORD  Password
      --clear-store        Clear password keystore

Description
===========

:program:`moderator` is used to manage mailing lists from the command line.

The sub-commands for :program:`moderator` are:

``list``
========

List the available ASF mailing lists.  This is restricted to public mailing
lists unless the user happens to be an ASF member, in which case private
mailing lists are included.  If the user happens to be an ASF committer then
the set of private mailing lists for those projects to which the committer
belongs are also included.

.. option:: mailing_list

An optional mailing list.  When this is supplied then members of that mailing
list email addresses are are listed.  Moderators are marked with an asterisk
at the end of their email address.  This option is only available for ASF
members or users who happen to be moderators of that mailing list.

``lookup``
==========

Lookup information of an ASF committer.  The ``lookup`` subcommand lists the
following information:

* whether the person looked up is an ASF member
* email aliases register to the person
* projects that the person belongs to
* incubator podlings that the person may be mentoring
* PMCs that the person may be a member of.   If that person is a chair of that PMC then that PMC will marked with an asterisk at the end

The list of a person's email aliases are withheld if the user is not an ASF
member or is not the same person as the user.

.. option:: email_alias

The email alias to lookup.

``add``
=======

Add an email address to a specific mailing list.  Only mailing list moderators
can add an email address to their own mailing list.  ASF members can add an
email address to any mailing list.

.. option:: mailing_list

The mailing list to add the email address to.

.. option:: email_address

The email address to add.

``remove``
==========

Remove an email address from a specific mailing list.  Only mailing list
moderators can remove an email address from their own mailing list.  ASF
members can remove an email address from any mailing list.

.. option:: mailing_list

The mailing list to remove the email address from.

.. option:: email_address

The email address to remove.

Examples
========

Manage the mailing list for ``dev@httpd.apache.org``::

    $ moderator lookup president@whitehouse.gov
    $ moderator list dev@httpd.apache.org
    $ moderator add dev@httpd.apache.org president@whitehouse.gov
    $ moderator remove dev@httpd.apache.org jschaefer@apache.org