Command-line interface
======================

Mojito provides a command-line interface for downloading bricks and catalogs, as
well as managing the local cache.

The CLI is available after installing the ``mojito`` package. You can invoke
help information using the following command:

.. code-block:: bash

    mojito --help

You can print help for specific subcommands as well:

.. code-block:: bash

    mojito cache-dir --help
    mojito download-brick --help
    mojito download-catalog --help
    mojito clear-cache --help
    mojito source-params --help

You can print the current version of Mojito using:

.. code-block:: bash

    mojito --version


Downloading bricks
------------------

Download individual bricks using the ``download-brick`` command. This
corresponds to the :func:`mojito.download.download_brick` function.

.. code-block:: bash

    mojito download-brick <brick-type> [source-id] [--version VERSION]
    [--reduced] [--cache-dir DIR] [--username USERNAME] [--token TOKEN]

**Arguments:**

* ``brick-type``: Type of brick to download (e.g., ``emri``, ``mbhb``,
  ``noise``)
* ``source-id``: (Optional) Source identifier for source-specific bricks
* ``--version``: Version number to download or ``latest`` (default: ``latest``)
* ``--reduced``: Download reduced/light bricks (downsampled, may miss quantities;
    not official L1 data)
* ``--cache-dir``: Override the default cache directory
* ``--username, -u``: Nextcloud username for authentication (uses
  ``MOJITO_USERNAME`` environment variable or prompts if not specified)
* ``--token, -t``: Nextcloud token for authentication (uses ``MOJITO_TOKEN``
  environment variable or prompts if not specified)

**Examples:**

.. code-block:: bash

    # Download the latest noise brick
    mojito download-brick noise

    # Download EMRI brick for source 42, version 3
    mojito download-brick emri 42 --version 3

    # Download to a custom cache directory
    mojito download-brick mbhb 100 --cache-dir /path/to/cache

    # Download with explicit authentication
    mojito download-brick mbhb 12 --username myuser --token mytoken

    # Download reduced brick (not official L1)
    mojito download-brick mbhb 12 --reduced


Downloading catalogs
--------------------

Download signal catalogs using the ``download-catalog`` command. This
corresponds to the :func:`mojito.download.download_catalog` function.

.. code-block:: bash

    mojito download-catalog <brick-type> [--version VERSION] [--cache-dir DIR]
    [--username USERNAME] [--token TOKEN]

**Arguments:**

* ``brick-type``: Type of catalog to download (e.g., ``emri``, ``mbhb``)
* ``--version``: Version number to download or ``latest`` (default: ``latest``)
* ``--cache-dir``: Override the default cache directory
* ``--username, -u``: Nextcloud username for authentication (uses
  ``MOJITO_USERNAME`` environment variable or prompts if not specified)
* ``--token, -t``: Nextcloud token for authentication (uses ``MOJITO_TOKEN``
  environment variable or prompts if not specified)

**Examples:**

.. code-block:: bash

    # Download the latest EMRI catalog
    mojito download-catalog emri

    # Download MBHB catalog version 2
    mojito download-catalog mbhb --version 2


Getting source parameters
--------------------------

Retrieve source parameters from a catalog using the ``source-params`` command. This
corresponds to the :func:`mojito.download.get_source_params` function.

.. code-block:: bash

    mojito source-params <brick-type> <source-id> [--version VERSION] [--cache-dir DIR]
    [--username USERNAME] [--token TOKEN]

**Arguments:**

* ``brick-type``: Type of catalog to retrieve parameters from (e.g., ``emri``, ``mbhb``)
* ``source-id``: Source identifier to retrieve parameters for
* ``--version``: Version number to download or ``latest`` (default: ``latest``)
* ``--cache-dir``: Override the default cache directory
* ``--username, -u``: Nextcloud username for authentication (uses
  ``MOJITO_USERNAME`` environment variable or prompts if not specified)
* ``--token, -t``: Nextcloud token for authentication (uses ``MOJITO_TOKEN``
  environment variable or prompts if not specified)

**Examples:**

.. code-block:: bash

    # Get parameters for source 12 from MBHB catalog
    mojito source-params mbhb 12

    # Get parameters from a specific version
    mojito source-params emri 42 --version 2

    # Use custom cache directory
    mojito source-params mbhb 100 --cache-dir /path/to/cache


Cache management
----------------

Mojito caches downloaded files locally to avoid redundant downloads. You can
manage this cache using the cache commands.

Get cache directory
~~~~~~~~~~~~~~~~~~~

Display the current cache directory path. This corresponds to the
:func:`mojito.download.get_cache_dir` function.

.. code-block:: bash

    mojito cache-dir [--cache-dir DIR]

**Example:**

.. code-block:: bash

    # Show default cache directory
    mojito cache-dir


Clear cache
~~~~~~~~~~~

Delete all cached Mojito files. This corresponds to the
:func:`mojito.download.clear_cache` function.

.. code-block:: bash

    mojito clear-cache [--cache-dir DIR] [-f/--force]

**Arguments:**

* ``--cache-dir``: Override the default cache directory
* ``-f/--force``: Skip the confirmation prompt

**Example:**

.. code-block:: bash

    # Delete all files in default cache (with confirmation)
    mojito clear-cache

    # Delete files in custom cache directory
    mojito clear-cache --cache-dir /custom/path

    # Force deletion without confirmation
    mojito clear-cache --force

.. warning::

    This operation cannot be undone. All downloaded bricks and catalogs will
    need to be re-downloaded.