# Command Line Interface

Dask provides a `dask` executable for a command line interface. Dask’s CLI is designed to be extensible allowing other projects in the Dask ecosystem (such as `distributed`) to add subcommands.

## Built-in commands

`dask` comes with the following commands.

### dask info

Information about your dask installation.

    dask info [OPTIONS] COMMAND [ARGS]...

#### versions

Print versions of Dask related projects.

    dask info versions [OPTIONS]

### dask docs

Open Dask documentation (https://docs.dask.org/) in a web browser.

    dask docs [OPTIONS]

## 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 `click.Command` and `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.

- The setuptools user guide.

- The poetry plugins documentation.

### Example: PEP-621

Since PEP-621, 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:

    # 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`:

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

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

    $ 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:

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

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

    from setuptools import setup

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