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’ll need uvicorn and jsbeautifier . They can be installed independently, but we recommend installing the standard group which conveniently bundles commonly used optional dependencies.

pip install litestar[standard]

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


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:


  2. app/

  3. Submodules of app


  5. application/

  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



The main entrypoint to the Litestar CLI is the litestar command.

If you don’t pass the --app flag, the application will be automatically discovered, as explained in Autodiscovery.



Environment variable




<modulename>.<submodule>:<app instance>



Look for the app in the specified directory by adding it to the PYTHONPATH. Defaults to the current working directory.


Prints the currently installed version of Litestar.




-s, --short



The run command executes a Litestar application using uvicorn.

litestar run


This feature is intended for development purposes only and should not be used to deploy production applications.



Environment variable


-r, --reload


Reload the application when files in its directory are changed

-R, --reload-dir


Specify directories to watch for reload.

-p, --port


Bind the server to this port [default: 8000]

--wc, --web-concurrency


The number of concurrent web workers to start [default: 1]

-H, --host


Bind the server to this host [default:]

--fd, --file-descriptor


Bind to a socket from this file descriptor.

--uds, --unix-domain-socket


Bind to a UNIX domain socket.

-d, --debug


Run the application in debug mode

--pdb, --use_pdb


Drop into the Python debugger when an exception occurs



Path to a SSL certificate file



Path to the private key to the SSL certificate



If the SSL certificate and key are not found, generate a self-signed certificate


The --reload-dir flag allows you to specify directories to watch for changes. If you specify this flag, the --reload flag is implied. You can specify multiple directories by passing the flag multiple times:

litestar run --reload-dir=. --reload-dir=../other-library/src

To set multiple directories via an environment variable, use a comma-separated list:


You can pass paths to an SSL certificate and it’s private key to run the server using the HTTPS protocol:

litestar run --ssl-certfile=certs/cert.pem --ssl-keyfile=certs/key.pem

Both flags must be provided and both files must exist. These are then passed to uvicorn. You can also use the --create-self-signed-cert flag:

litestar run --ssl-certfile=certs/cert.pem --ssl-keyfile=certs/key.pem --create-self-signed-cert

This way, if the given files don’t exist, a self-signed certificate and a passwordless key will be generated. If the files are found, they will be reused.


The info command displays useful information about the selected application and its configuration.

litestar info
litestar info


The routes command displays a tree view of the routing table.

litestar routes
litestar info


This command and its subcommands provide management utilities for server-side session backends.


The delete subcommand deletes a specific session from the backend.

litestar sessions delete cc3debc7-1ab6-4dc8-a220-91934a473717


The clear subcommand is used to remove all sessions from the backend.

litestar sessions clear


This command provides utilities to generate OpenAPI schemas and TypeScript types.


The schema subcommand generates OpenAPI specifications from the Litestar application and serializes them as either JSON or YAML. The serialization format depends on the filename, which is by default openapi_schema.json. You can specify a different filename using the –output flag. For example:

litestar schema openapi --output my-specs.yml


The typescript subcommand generates TypeScript definitions from the Litestar application’s OpenAPI specifications. For example:

litestar schema typescript

By default, this command outputs a file called api-specs.ts. You can change this using the –output option:

litestar schema typescript --output my-types.ts

You can also specify the top-level TypeScript namespace that will be created, which is API by default:

export namespace API {
    // ...

To do this, use the –namespace option:

litestar schema typescript --namespace MyNamespace

This will result in:

export namespace MyNamespace {
    // ...

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:

from setuptools import setup

        "litestar.commands": ["my_command=my_litestar_plugin.cli:main"],
Using PDM#
my_command = "my_litestar_plugin.cli:main"

# Or, as an entrypoint:

my_command = "my_litestar_plugin.cli:main"
Using Poetry#
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:

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

class CLIPlugin(CLIPluginProtocol):
    def on_cli_init(self, cli: Group) -> None:
        def is_debug_mode(app: Litestar):

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.

import click
from litestar import Litestar

def my_command(app: Litestar) -> None:

CLI Reference#

For more information, visit the Litestar CLI Click API Reference.