Skip to content

Command Line Interface (CLI)

Ushka comes with a powerful command-line interface (CLI) to help you with common development tasks. You interact with it through the ushka command.

To see a list of all available commands, you can run: 

ushka --help

Core Commands

new

Scaffolds a new Ushka project directory.

ushka new <project_name>
This creates a new folder with a basic project structure, including an ushka.toml file, an apps/home directory, and a templates directory.

add

Adds a new application to an existing Ushka project.

ushka add <app_name>
This command creates a new directory under apps/ (e.g., apps/products/) and populates it with __init__.py, views.py, models.py, and a basic app.toml. It also automatically adds the new app to the [apps].installed list in your main ushka.toml.

dev

Starts the development server with auto-reloading enabled.

ushka dev
This is the command you'll use most often during development. The server will automatically restart whenever you save a file.

You can specify a different host or port: 

ushka dev --host 0.0.0.0 --port 5000

run

Starts the production server.

ushka run
This command is for running your application in a production environment. It does not have auto-reloading and is optimized for performance. It's recommended to use a process manager like Gunicorn or Supervisor to manage the ushka run process in production.

db Commands

The db command is a namespace for all database migration commands, which are powered by Alembic.

db init

Initializes the database migration environment. Creates the migrations/ directory and alembic.ini. Run this only once per project.

db make

Auto-generates a new migration script based on changes detected in your models. 

ushka db make -m "A short description of the change"

db migrate

Applies all pending migrations to the database.

db revert

Reverts the last applied migration.

db status

Shows the current revision of the database.

db history

Shows the full migration history.

routes Commands

routes list

Lists all discovered and registered routes in your application, including their HTTP method and URL path. This is extremely useful for debugging.

queue Commands

The queue command is a namespace for managing the background task queue.

queue process

Starts a worker that processes tasks from the queue. 

# Process a single task and exit
ushka queue process

# Process up to 10 tasks and exit
ushka queue process --max-tasks 10
This command is typically run on a schedule (e.g., via a cron job) or continuously by a process manager.