CLI Reference

Keywords: asok cli commands, create command, database commands, custom cli command, make migration, database migrations, asok migrate

The asok command-line tool provides a professional, styled interface to help you create, develop, and manage your project.

Commands

asok create <name>

Create a new project. Asok features a Smart Interactive Mode: if you don’t provide any flags, it will guide you through the setup with questions.

asok create myapp
#   ? Add Tailwind CSS support? [y/N]: y
#   ? Add Admin interface? [y/N]: y
#
# 🚀 Creating Asok project: myapp...
#   ✅ Project 'myapp' created!

Flags (Direct Mode)

Skip questions by providing flags explicitly:

asok create myapp --tailwind --admin

asok createsuperuser

Create an administrative account. Now uses a conversational, professional prompt system:

asok createsuperuser
#   CREATE SUPERUSER
#   Enter your email address: admin@example.com
#   Enter your password: 
#   Confirm your password: 
#   ✅ Created 'admin' role with full permissions.
#   ✅ Superuser created: admin@example.com

asok dev

Start the development server with auto-reload and live browser reload:

asok dev
#
# DEVELOPMENT SERVER
#   Reloader ● Active (PID: 12345)
#   URL      http://127.0.0.1:8000
#   Tailwind ● Watching...

Watches .py, .html, .json, .css, .js files and .env across the project (root, src/, and asok/).

asok migrate

Apply or rollback database migrations. This command manages your database schema version by applying pending migration files or reverting already applied ones.

asok migrate [options]

Options

  • --status: Show the current status of all migrations (applied vs. pending). Displays a checklist where [X] indicates applied and [ ] indicates pending.

  • --rollback: Revert migrations. By default, this rolls back the last batch of migrations that were applied together.

  • --steps <N>: Revert exactly N migrations. Must be used in combination with --rollback.

  • --to <migration_name>: Migrate up or down to a specific target migration.

    • If the target migration is not yet applied, all pending migrations up to and including it will be applied.

    • If the target migration is already applied, all migrations applied after it will be rolled back.

  • --reset: Roll back all applied migrations in the database (reverts the entire schema back to empty/start).

  • --fake: Update the migrations tracking table without actually running the database schema modification queries.

    • Used to mark pending migrations as applied (when migrating forward).

    • Used to mark applied migrations as reverted (when rolling back).

  • --database <connection_name>: Specify a specific database routing engine from your configuration (default is the default database connection).

# Example Usage:
asok migrate                     # Apply all pending migrations
asok migrate --status            # Check which migrations are applied
asok migrate --rollback --steps 2 # Revert the last 2 migrations
asok migrate --to=0002_add_posts # Align schema with migration '0002_add_posts'

asok make migration <name>

Detect codebase changes and generate a new declarative database migration file.

asok make migration <name>

Asok includes a Smart Autodetector that automatically generates schema migrations for you:

  1. Analyze Codebase: It imports all model classes defined under src/models/ to understand the current schema you want.

  2. Reconstruct History: It reads and executes the operations in all existing migration files inside src/migrations/ to rebuild the historical state of the database.

  3. Diff Schema: It compares the current model definitions against the historical state.

  4. Generate File: If any schema differences (like added tables, new columns, altered fields, or removed indices) are detected, it creates a new versioned migration file (e.g., src/migrations/0003_add_phone_to_users.py) containing the declarative operations representing the differences.

If no changes are detected, the command will simply exit with No changes detected in models..

asok db <command>

Introspect database schema and query execution plan details.

  • asok db schema: List all database tables, columns, data types, and primary/foreign keys.

  • asok db explain "<query>": Show the execution/query plan of a given SQL query using the active database engine.

asok db schema                   # Inspect Default Database Schema
asok db schema --database=replica # Inspect specific database schema
asok db explain "SELECT * FROM users" # Explain query on default database

asok dumpdata

Export database records of registered models to a JSON fixture file.

asok dumpdata                  # Dump all models to stdout
asok dumpdata --output=f.json  # Dump all models to f.json
asok dumpdata User             # Dump only the 'User' model to stdout

Binary database column values (e.g. vector blobs or files) are encoded using Base64 with a "base64:" prefix.

asok loaddata

Import/restore database records from a JSON fixture file.

asok loaddata fixtures.json

Existing records are updated (matched by primary key) using standard ORM .save(). Non-existent records are inserted using raw SQL statements to preserve the original primary key ID. The entire loading process is wrapped in a database transaction for performance and atomicity.

asok seed

Populate the database with test data:

asok seed
#
# SEEDING DATA
#   ✅ Seeding complete.

asok routes

List all registered routes in a clean, tabular format:

asok routes
#
# ROUTES
#   URL          HANDLER
#   -----------   ---------------
#   /             page.py
#   /about        page.html
#   /blog/[slug]  page.py

asok shell

Open an interactive Python shell with the app instance and all your models pre-imported:

asok shell
#
# Asok Shell (Interactive Python)
# ℹ️ All models and 'app' instance pre-imported.
#
# Output: Asok shell with models loaded (User, Post, Comment)
# Python 3.12
# >>> User.count()

asok image

Manage your Image Optimization system (WebP conversion).

  • asok image --install: Download the cwebp standalone binary.

  • asok image --enable: Enable optimization on an existing project. Installs binary and sets IMAGE_OPTIMIZATION=true in .env.

  • asok image --optimize: Full project scan. Converts all existing JPG/PNG images in src/partials/ and src/uploads/ to WebP.

asok tailwind

Manage your Tailwind CSS integration.

  • asok tailwind --install: Download the binary.

  • asok tailwind --build: Run a one-shot build.

  • asok tailwind --enable: Setup Tailwind on an existing project (adds imports to CSS and links to HTML).

asok admin

Manage the Admin interface.

  • asok admin --enable: Retro-fit the Admin interface into an existing project. Handles wsgi.py updates and User model scaffolding.

asok make <type> <name>

Scaffold new project components:

  • asok make model User

  • asok make middleware Auth

  • asok make page Dashboard

  • asok make component SearchBar

To generate database migrations, use the specialized asok make migration command instead.

asok build

Generate an optimized production distribution in the dist/ folder:

asok build                     # Standard optimized build
asok build --with-db           # Include current database
asok build --output my-dist    # Custom output folder
asok build --keep-source       # Keep .py files alongside .pyc

The build process includes:

  • Minification: Recursive JS/CSS and HTML minification.

  • Bytecode: Compilation of all Python files to .pyc (sources removed).

  • Images: Automatic WebP conversion if enabled.

  • Production Config: Generation of .env.production.

asok preview

Run the application in production mode locally:

asok preview
#
# PREVIEW SERVER (PRODUCTION MODE)
#   URL  http://127.0.0.1:8000
# ℹ️ No auto-reload — restart manually after changes

asok worker [action]

Start the background task queue worker process, or view queue status (only when using the redis background queue backend):

  • asok worker (or asok worker run): Starts the worker process. It listens to queues defined by the ASOK_WORKER_QUEUES environment variable (default: high,default,low).

  • asok worker status: Connects to Redis and displays the pending task count and details for each queue (high, default, low, and the Dead Letter Queue asok:dlq).

asok worker status
#
# ASOK QUEUE STATUS
#   Backend: redis
#   Redis URL: redis://localhost:6379/0
# --------------------------------------------------
#   Queue: asok:queue:high | Pending tasks: 0
#     ✓ No pending tasks.
#
#   Queue: asok:queue:default | Pending tasks: 2
#     Next tasks to process:
#
#      1. src.tasks.send_email('user@example.com')
#      2. src.tasks.generate_report(42)
#
#   Queue: asok:queue:low | Pending tasks: 0
#     ✓ No pending tasks.
#
#   Queue: asok:dlq | Pending tasks: 0
#     ✓ No pending tasks.

asok test [path]

Discover and run unit tests in your project using the built-in test runner.

asok test            # Run all tests in the 'tests/' directory
asok test tests/unit # Run tests in a specific directory or file

asok deploy

Generate production deployment configuration files (Nginx, Gunicorn, SystemD, setup script) for your project.

asok deploy                     # Standard configuration setup
asok deploy --prod-dir=/var/www # Custom production directory path

asok assets

Manage JavaScript and CSS assets in your project.

  • asok assets --install: Download the esbuild standalone binary for asset minification.

  • asok assets --minify: Minify JS/CSS assets in src/partials recursively.