CLI

Litestar provides a convenient command line interface (CLI) for running and managing Litestar applications. The CLI is powered by click, rich, and rich-click.

Enabling all CLI features

The CLI and its hard dependencies are included by default. However, if you want to run your application (using litestar run ) or beautify the Typescript generated by the litestar schema typescript command, you will need uvicorn and jsbeautifier. They can be installed independently, but we recommend installing the standard extra which conveniently bundles commonly used optional dependencies.

Install the standard group

pip install litestar[standard]

Once you have installed standard, you will have access to the litestar run command.

Autodiscovery

Litestar offers autodiscovery of applications and application factories placed within the canonical modules named either app or application. These modules can be individual files or directories. Within these modules or their submodules, the CLI will detect any instances of Litestar, callables named create_app, or callables annotated to return a Litestar instance.

The autodiscovery follows these lookup locations in order:

1. app.py

2. app/__init__.py

3. Submodules of app

4. application.py

5. application/__init__.py

6. Submodules of application

Within these locations, Litestar CLI looks for:

1. An object named app that is an instance of Litestar

2. An object named application that is an instance of Litestar

3. Any object that is an instance of Litestar

4. A callable named create_app

5. A callable annotated to return an instance of Litestar

Extending the CLI

Litestar’s CLI is built with click and can be extended by making use of entry points, or by creating a plugin that conforms to the CLIPluginProtocol.

Using entry points

Entry points for the CLI can be added under the litestar.commands group. These entries should point to a click.Command or click.Group:

setup.py

Using setuptools

from setuptools import setup

setup(
   name="my-litestar-plugin",
   ...,
   entry_points={
       "litestar.commands": ["my_command=my_litestar_plugin.cli:main"],
   },
)

pdm

Using PDM

[project.scripts]
my_command = "my_litestar_plugin.cli:main"

# Or, as an entrypoint:

[project.entry-points."litestar.commands"]
my_command = "my_litestar_plugin.cli:main"

Poetry

Using Poetry

[tool.poetry.plugins."litestar.commands"]
my_command = "my_litestar_plugin.cli:main"

Using a plugin

A plugin extending the CLI can be created using the CLIPluginProtocol. Its on_cli_init() will be called during the initialization of the CLI, and receive the root click.Group as its first argument, which can then be used to add or override commands:

Creating a CLI plugin

from litestar import Litestar
from litestar.plugins import CLIPluginProtocol
from click import Group


class CLIPlugin(CLIPluginProtocol):
    def on_cli_init(self, cli: Group) -> None:
        @cli.command()
        def is_debug_mode(app: Litestar):
            print(app.debug)


app = Litestar(plugins=[CLIPlugin()])

Accessing the app instance

When extending the Litestar CLI, you will most likely need access to the loaded Litestar instance. You can achieve this by adding the special app parameter to your CLI functions. This will cause the Litestar instance to be injected into the function whenever it is called from a click-context.

Accessing the app instance programmatically

import click
from litestar import Litestar


@click.command()
def my_command(app: Litestar) -> None: ...

CLI Reference

The most up-to-date reference for the Litestar CLI can be found by running:

Display the CLI help

litestar --help

You can also visit the Litestar CLI Click API Reference for that same information.