feat(command): add get-api-token command

docs/source/contributer_documentation/commands.rst

@@ -412,6 +412,19 @@ purge-remote-media
  :undoc-members:
  :show-inheritance:
 
+get_api_token
+-------------
+
+.. automodule:: matrixctl.commands.get_api_token.parser
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+.. automodule:: matrixctl.commands.get_api_token.addon
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
 delete-local-media
 ------------------
 

src/matrixctl/commands/get_api_token/__init__.py

@@ -0,0 +1,20 @@
+# matrixctl
+# Copyright (c) 2020-2023  Michael Sasser <Michael@MichaelSasser.org>
+#
+# 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.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Use the modules of this package to add functionality to Matrixctl."""
+
+
+# vim: set ft=python :

src/matrixctl/commands/get_api_token/addon.py

@@ -0,0 +1,56 @@
+# matrixctl
+# Copyright (c) 2020-2025  Michael Sasser <Michael@MichaelSasser.org>
+#
+# 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.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Use this module to add the ``get-api-token`` subcommand to ``matrixctl``."""
+
+from __future__ import annotations
+
+import logging
+
+from argparse import Namespace
+
+from matrixctl.handlers.yaml import YAML
+
+
+__author__: str = "Michael Sasser"
+__email__: str = "Michael@MichaelSasser.org"
+
+logger = logging.getLogger(__name__)
+
+
+def addon(_arg: Namespace, yaml: YAML) -> int:
+    """Get an API token.
+
+    Parameters
+    ----------
+    arg : argparse.Namespace
+        The ``Namespace`` object of argparse's ``parse_args()``.
+    yaml : matrixctl.handlers.yaml.YAML
+        The configuration file handler.
+
+    Returns
+    -------
+    err_code : int
+        Non-zero value indicates error code, or zero on success.
+
+    """
+    print(yaml.get_api_token())
+    logger.debug("API token successfully retrieved.")
+
+    return 0
+
+
+# vim: set ft=python :

src/matrixctl/commands/get_api_token/parser.py

@@ -0,0 +1,59 @@
+# matrixctl
+# Copyright (c) 2020-2025  Michael Sasser <Michael@MichaelSasser.org>
+#
+# 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.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Use this module to add the ``get-api-token`` subcommand to ``matrixctl``."""
+
+from __future__ import annotations
+
+import typing as t
+
+from argparse import ArgumentParser
+from argparse import _SubParsersAction
+
+from matrixctl.command import SubCommand
+from matrixctl.command import subparser
+
+
+__author__: str = "Michael Sasser"
+__email__: str = "Michael@MichaelSasser.org"
+
+
+@subparser(SubCommand.SERVER)
+def subparser_get_api_token(
+    subparsers: _SubParsersAction[t.Any],
+    common_parser: ArgumentParser,
+) -> None:
+    """Create a subparser for the ``matrixctl get-api-token`` command.
+
+    Parameters
+    ----------
+    subparsers : argparse._SubParsersAction of typing.Any
+        The object which is returned by ``parser.add_subparsers()``.
+
+    Returns
+    -------
+    None
+
+    """
+    parser: ArgumentParser = subparsers.add_parser(
+        "get-api-token",
+        help=("Get an API token from your homeserver"),
+        parents=[common_parser],
+    )
+    parser.set_defaults(addon="get_api_token")
+
+
+# vim: set ft=python :