Command Line Interface
======================

Dask provides a ``dask`` executable for a command line interface.
Dask's CLI is :ref:`designed to be extensible <extending-cli>` allowing
other projects in the Dask ecosystem (such as ``distributed``) to
add subcommands.

Built-in commands
-----------------

``dask`` comes with the following commands.

.. click:: dask.cli:info
   :prog: dask info
   :show-nested:

.. click:: dask.cli:docs
   :prog: dask docs
   :show-nested:


.. _extending-cli:

Extending the Dask CLI
----------------------

.. note::

    This section is intended for library authors who want to
    integrate their library with the ``dask`` CLI.

Third party packages can extend the ``dask`` command line tool via
entry points and Click_. Dask will discover :obj:`click.Command` and
:obj:`click.Group` objects registered as entry points under the
``dask_cli`` namespace. Below you'll find two examples which augment
the ``dask`` CLI by adding a ``dask_cli`` entry point to a project.

Click provides great documentation for writing commands; more
documentation on entry points can be found at:

- `The python packaging documentation
  <https://setuptools.pypa.io/en/latest/userguide/entry_point.html>`_.
- `The setuptools user guide
  <https://setuptools.pypa.io/en/latest/userguide/entry_point.html>`_.
- `The poetry plugins documentation
  <https://python-poetry.org/docs/pyproject/#plugins>`_.

Example: PEP-621
~~~~~~~~~~~~~~~~

Since `PEP-621 <https://peps.python.org/pep-0621/>`_, if starting a
new project, the canonical way to add an entry point to your Python
project is to use the ``[project.entry-points]`` table in the
``pyproject.toml`` file. This method should be picked up by any Python
build system that is compatible with ``PEP-621``'s ``project``
configuration. Hatch_, Flit_, and setuptools_ (version 61.0.0 or
later) are three example build systems which are PEP-621 compatible
and use ``[project.entry-points]``.

For example, if your project is called ``mypackage``, and it contains
a ``cli.py`` module under the ``mypackage`` namespace with the
following contents:

.. code-block::

   # in the file mypackage/cli.py
   import click

   @click.command(name="mycommand")
   @click.argument("name", type=str)
   @click.option("-c", "--count", default=1)
   def main(name, count):
       for _ in range(count):
           click.echo(f"hello {name} from mycommand!")

You can create an entry point that will be discovered by Dask by
adding to ``pyproject.toml``:

.. code-block:: toml

    [project.entry-points."dask_cli"]
    mycommand = "mypackage.cli:main"

After installing ``mypackage``, the ``mycommand`` subcommand should be
available to the ``dask`` CLI:

.. code-block:: shell

   $ dask mycommand world
   hello world from mycommand!

   $ dask mycommand user -c 3
   hello user from mycommand!
   hello user from mycommand!
   hello user from mycommand!

Example: setup.cfg and setup.py
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. note::

   If you are starting a new project the recommendation from the
   Python Packaging Authority (PyPA_) is to use PEP-621, these
   setuptools instructions are provided for existing projects.

If your project already uses ``setuptools`` with a ``setup.cfg`` file
and/or a ``setup.py`` file, we can create an entry point for the same
``mycommand.cli:main`` function introduced in the previous section. If
using ``setup.cfg``, the entry point can be registered by adding the
following block to the file:

.. code-block:: ini

   [options.entry_points]
   dask_cli =
       mycommand = mypackage.cli:main

Or the entry point can be registered directly in ``setup.py`` with:

.. code-block:: python

   from setuptools import setup

   setup(
       ...
       entry_points="""
           [dask_cli]
           mycommand=mypackage.cli:main
       """,
   )

.. _Click: https://click.palletsprojects.com/
.. _Hatch: https://github.com/pypa/hatch
.. _setuptools: https://setuptools.pypa.io/en/latest/index.html
.. _PyPA: https://pypa.io/
.. _Flit: https://flit.pypa.io/