cli

Command line interface for the application.

Litestar CLI

app

Litestar CLI.

The application to will be automatically discovered if it’s in one of these canonical paths: ‘app.py’, ‘asgi.py’, ‘application.py’ or ‘app/__init__.py’. When auto-discovering application factories, functions with the name ‘create_app’ are considered, or functions that are annotated as returning a ‘Litestar’ instance.

Alternatively, the application can be specified explicitly via the ‘–app’ option (‘litestar –app=<module name>.<submodule>:<app instance or factory>’) or the ‘LITESTAR_APP’ environment variable of the same name.

Usage

app [OPTIONS] COMMAND [ARGS]...

Options

--app <app_path>

Module path to a Litestar application

--app-dir <app_dir>

Look for APP in the specified directory, by adding this to the PYTHONPATH. Defaults to the current working directory.

info

Show information about the detected Litestar app.

Usage

app info [OPTIONS]

routes

Display information about the application’s routes.

Usage

app routes [OPTIONS]

Options

--schema

Include schema routes

--exclude <exclude>

routes to exclude via regex

run

Run a Litestar app. (requires ‘uvicorn’ to be installed).

The application will be automatically discovered, or can be set as an option to the main ‘litestar’ command. Run ‘litestar –help’ for more information about app autodiscovery

Usage

app run [OPTIONS]

Options

-r, --reload

Reload server on changes

-R, --reload-dir <reload_dir>

Directories to watch for file changes

-I, --reload-include <reload_include>

Glob patterns for files to include when watching for file changes

-E, --reload-exclude <reload_exclude>

Glob patterns for files to exclude when watching for file changes

-p, --port <port>

Serve under this port

Default:

8000

-W, --wc, --web-concurrency <wc>

The number of HTTP workers to launch

Default:

1

-H, --host <host>

Server under this host

Default:

'127.0.0.1'

-F, --fd, --file-descriptor <fd>

Bind to a socket from this file descriptor.

-U, --uds, --unix-domain-socket <uds>

Bind to a UNIX domain socket.

-d, --debug

Run app in debug mode

-P, --pdb, --use-pdb

Drop into PDB on an exception

--ssl-certfile <ssl_certfile>

Location of the SSL cert file

--ssl-keyfile <ssl_keyfile>

Location of the SSL key file

--create-self-signed-cert

If certificate and key are not found at specified locations, create a self-signed certificate and a key

Environment variables

LITESTAR_RELOAD

Provide a default for -r

LITESTAR_RELOAD_DIRS

Provide a default for -R

LITESTAR_RELOAD_INCLUDES

Provide a default for -I

LITESTAR_RELOAD_EXCLUDES

Provide a default for -E

LITESTAR_PORT

Provide a default for -p

['LITESTAR_WEB_CONCURRENCY', 'WEB_CONCURRENCY']

Provide a default for -W

LITESTAR_HOST

Provide a default for -H

LITESTAR_FILE_DESCRIPTOR

Provide a default for -F

LITESTAR_UNIX_DOMAIN_SOCKET

Provide a default for -U

LITESTAR_DEBUG

Provide a default for -d

LITESTAR_PDB

Provide a default for -P

LITESTAR_SSL_CERT_PATH

Provide a default for --ssl-certfile

LITESTAR_SSL_KEY_PATH

Provide a default for --ssl-keyfile

LITESTAR_CREATE_SELF_SIGNED_CERT

Provide a default for --create-self-signed-cert

schema

Manage server-side OpenAPI schemas.

Usage

app schema [OPTIONS] COMMAND [ARGS]...

openapi

Generate an OpenAPI Schema.

Usage

app schema openapi [OPTIONS]

Options

--output <output>

output file path

Default:

PosixPath('openapi_schema.json')

typescript

Generate TypeScript specs from the OpenAPI schema.

Usage

app schema typescript [OPTIONS]

Options

--output <output>

output file path

Default:

PosixPath('api-specs.ts')

--namespace <namespace>

namespace to use for the typescript specs

sessions

Manage server-side sessions.

Usage

app sessions [OPTIONS] COMMAND [ARGS]...

clear

Delete all sessions.

Usage

app sessions clear [OPTIONS]

delete

Delete a specific session.

Usage

app sessions delete [OPTIONS] SESSION_ID

Arguments

SESSION_ID

Required argument

version

Show the currently installed Litestar version.

Usage

app version [OPTIONS]

Options

-s, --short

Exclude release level and serial information

Database CLI

app database

Manage SQLAlchemy database components.

Usage

app database [OPTIONS] COMMAND [ARGS]...

branches

Show current branch points in the migration history

Usage

app database branches [OPTIONS]

Options

--bind-key <bind_key>

Specify which SQLAlchemy config to use by bind key

--verbose

Enable verbose output.

check

Check if the target database is up to date

Usage

app database check [OPTIONS]

Options

--bind-key <bind_key>

Specify which SQLAlchemy config to use by bind key

downgrade

Downgrade database to a specific revision.

Usage

app database downgrade [OPTIONS] [REVISION]

Options

--bind-key <bind_key>

Specify which SQLAlchemy config to use by bind key

--sql

Generate SQL output for offline migrations.

--tag <tag>

an arbitrary ‘tag’ that can be intercepted by custom env.py scripts via the .EnvironmentContext.get_tag_argument method.

--no-prompt

Do not prompt for confirmation before executing the command.

Default:

False

Arguments

REVISION

Optional argument

drop-all

Drop all tables from the database.

Usage

app database drop-all [OPTIONS]

Options

--bind-key <bind_key>

Specify which SQLAlchemy config to use by bind key

--no-prompt

Do not prompt for confirmation before executing the command.

Default:

False

dump-data

Dump specified tables from the database to JSON files.

Usage

app database dump-data [OPTIONS]

Options

--bind-key <bind_key>

Specify which SQLAlchemy config to use by bind key

--table <table_names>

Required Name of the table to dump. Multiple tables can be specified. Use ‘*’ to dump all tables.

--dir <dump_dir>

Directory to save the JSON files. Defaults to WORKDIR/fixtures

edit

Edit a revision file using $EDITOR

Usage

app database edit [OPTIONS] REVISION

Options

--bind-key <bind_key>

Specify which SQLAlchemy config to use by bind key

Arguments

REVISION

Required argument

ensure-version

Create the alembic version table if it doesn’t exist

Usage

app database ensure-version [OPTIONS]

Options

--bind-key <bind_key>

Specify which SQLAlchemy config to use by bind key

--sql

Generate SQL output instead of executing

heads

Show current available heads in the script directory

Usage

app database heads [OPTIONS]

Options

--bind-key <bind_key>

Specify which SQLAlchemy config to use by bind key

--verbose

Enable verbose output.

--resolve-dependencies

Resolve dependencies between heads

history

List changeset scripts in chronological order

Usage

app database history [OPTIONS]

Options

--bind-key <bind_key>

Specify which SQLAlchemy config to use by bind key

--verbose

Enable verbose output.

--rev-range <rev_range>

Revision range (e.g., ‘base:head’, ‘abc:def’)

--indicate-current

Indicate the current revision

init

Initialize migrations for the project.

Usage

app database init [OPTIONS] [DIRECTORY]

Options

--bind-key <bind_key>

Specify which SQLAlchemy config to use by bind key

--multidb

Support multiple databases

--package

Create __init__.py for created folder

--no-prompt

Do not prompt for confirmation before executing the command.

Default:

False

Arguments

DIRECTORY

Optional argument

list-templates

List available Alembic migration templates

Usage

app database list-templates [OPTIONS]

Options

--bind-key <bind_key>

Specify which SQLAlchemy config to use by bind key

make-migrations

Create a new migration revision.

Usage

app database make-migrations [OPTIONS]

Options

--bind-key <bind_key>

Specify which SQLAlchemy config to use by bind key

-m, --message <message>

Revision message

--autogenerate, --no-autogenerate

Automatically populate revision with detected changes

--sql

Export to .sql instead of writing to the database.

--head <head>

Specify head revision to use as base for new revision.

--splice

Allow a non-head revision as the “head” to splice onto

--branch-label <branch_label>

Specify a branch label to apply to the new revision

--version-path <version_path>

Specify specific path from config for version file

--rev-id <rev_id>

Specify a ID to use for revision.

--no-prompt

Do not prompt for confirmation before executing the command.

Default:

False

merge

Merge two revisions together, creating a new migration file

Usage

app database merge [OPTIONS] REVISIONS

Options

--bind-key <bind_key>

Specify which SQLAlchemy config to use by bind key

-m, --message <message>

Merge message

--branch-label <branch_label>

Branch label for merge revision

--rev-id <rev_id>

Specify custom revision ID

--no-prompt

Do not prompt for confirmation before executing the command.

Default:

False

Arguments

REVISIONS

Required argument

show

Show the revision denoted by the given symbol

Usage

app database show [OPTIONS] REVISION

Options

--bind-key <bind_key>

Specify which SQLAlchemy config to use by bind key

Arguments

REVISION

Required argument

show-current-revision

Shows the current revision for the database.

Usage

app database show-current-revision [OPTIONS]

Options

--bind-key <bind_key>

Specify which SQLAlchemy config to use by bind key

--verbose

Enable verbose output.

stamp

Stamp the revision table with the given revision; don’t run any migrations

Usage

app database stamp [OPTIONS] REVISION

Options

--bind-key <bind_key>

Specify which SQLAlchemy config to use by bind key

--sql

Generate SQL output for offline migrations

--tag <tag>

Arbitrary ‘tag’ that can be intercepted by custom env.py scripts

--purge

Delete all entries in version table before stamping

Arguments

REVISION

Required argument

upgrade

Upgrade database to a specific revision.

Usage

app database upgrade [OPTIONS] [REVISION]

Options

--bind-key <bind_key>

Specify which SQLAlchemy config to use by bind key

--sql

Generate SQL output for offline migrations.

--tag <tag>

an arbitrary ‘tag’ that can be intercepted by custom env.py scripts via the .EnvironmentContext.get_tag_argument method.

--no-prompt

Do not prompt for confirmation before executing the command.

Default:

False

Arguments

REVISION

Optional argument

User management CLI

app user

Manage application users and roles.

Usage

app user [OPTIONS] COMMAND [ARGS]...

create-roles

Create pre-configured application roles and assign to users.

Usage

app user create-roles [OPTIONS]

create-user

Create a user

Usage

app user create-user [OPTIONS]

Options

--email <email>

Email of the new user

--name <name>

Full name of the new user

--password <password>

Password

--superuser

Is a superuser

promote-to-superuser

Promotes a user to application superuser

Usage

app user promote-to-superuser [OPTIONS]

Options

--email <email>

Email of the user