Flaxon 0.3.0 and Teloce-Py 0.3.0 are available on PyPI. Release instructions are maintained on this site; source links identify the framework snapshot. Check version and upgrade guidance.

Framework source · Markdown

CLI Reference

The flaxon command is installed automatically with the framework. Every command that takes an application argument expects it in module:variable form — the Python file (without .py) before the colon, the Flaxon(...) instance's variable name after it. Run these from the directory containing that file, or the app won't be importable.

flaxon --help          # list every command
flaxon --version       # show the installed Flaxon version
flaxon <command> --help  # full options for one command

flaxon run

Starts your app with Uvicorn.

flaxon run app:app --reload

flaxon routes

Lists every registered HTTP and WebSocket route.

$ flaxon routes app:app
Routes for bookstore
Method  Path                  Name
-----------------------------------------
GET     /                     home
GET     /books                list_books
POST    /books                create_book
DELETE  /books/<int:book_id>  delete_book

--format json or --format csv for machine-readable output, --output FILE to save instead of printing.

flaxon doctor

Runs diagnostics against your app: confirms it imports, counts routes, flags missing configuration.

$ flaxon doctor app:app
Flaxon Doctor - bookstore
[PASS] Application imported successfully
[PASS] 4 HTTP route(s) registered
[PASS] 0 WebSocket route(s) registered
[WARN] A strong production SECRET_KEY is not configured.
Result: 1 warning(s), 0 failure(s)

--fix attempts automatic fixes for what it finds.

flaxon new

Scaffolds a modular Flaxon + Teloce welcome application by default, including TypeScript, scoped component styles, a Python API, SQLite migrations, and a protected admin.

After generation, install the project, run python management.py makemigrations and python management.py migrate, and create your administrator with python management.py setup-admin. There is no default password. The generated project also includes flaxon welcome and flaxon welcome-status, registered by its welcome module through flaxon_cli.py. Use --template basic for the smaller API-only starter. See getting started for the complete workflow.

flaxon new my-project

--template NAME picks a starter template, --no-venv skips creating a virtualenv.

flaxon generate

Scaffolds a single component — not a full project.

flaxon generate model Product
flaxon generate controller ProductController
flaxon generate service EmailService

Valid types: controller, schema, service, middleware, model, task. --path DIR sets where it's written (defaults to the current directory).

flaxon docs

Generates an OpenAPI spec by reading your actual routes, endpoint docstrings, and Schema-typed parameters — no manual descriptions required for the basics.

$ flaxon docs app:app --title "Bookstore API"
✓ Wrote OpenAPI spec for 2 path(s) to openapi.json

What actually gets extracted, automatically, from your code: - Summary/description — your endpoint's docstring (first line = summary, rest = description). - Request body schema — any parameter typed as a Schema subclass gets its fields, types, and constraints (min_length, minimum, etc.) pulled straight from the class definition. - Path parameters — Flaxon's <int:id>-style converters get correctly typed and converted to OpenAPI's {id} format.

The output is a plain JSON file — hand-edit it afterward for anything auto-detection can't infer (security schemes, examples, descriptions on bare int/str parameters), or just re-run the command to regenerate the parts that come from your code.

flaxon inspect

Shows detailed information about a running app's configuration.

$ flaxon inspect app:app --middleware --config
Application: bookstore
Debug: False
Middleware:
  - (<class 'flaxon.middleware.request_id.RequestIDMiddleware'>, {})
  - (<class 'flaxon.middleware.security_headers.SecurityHeadersMiddleware'>, {})
Config:
  ENV: development
  DEBUG: False
  SECRET_KEY: None
  ALLOWED_HOSTS: ['localhost', '127.0.0.1']
  MAX_BODY_SIZE: 10485760
  TRUSTED_PROXIES: []
  PROXY_HEADERS: ['x-forwarded-for', 'x-forwarded-proto', 'x-forwarded-host']

--middleware / --config toggle those sections; --format {json,yaml,table} controls output format.

flaxon build

Wraps python -m build to produce a wheel and/or sdist for publishing.

flaxon build --format wheel

--format {wheel,sdist,all} (default all), --output DIR for the output directory.

flaxon test

Wraps pytest.

flaxon test
flaxon test tests/test_routing.py --coverage -v

--coverage generates a coverage report, --verbose/-v for verbose output, --keep-env keeps the test environment around after the run. Requires pytest installed (pip install flaxon[dev] covers this).

flaxon shell

Launches a Python REPL with your application already imported and available.

flaxon shell app:app

--no-import skips loading the application, for a plain Python shell.

flaxon migrate

Applies or rolls back database migrations.

flaxon migrate --direction up
flaxon migrate --direction down --target 0003 --dry-run

--direction {up,down}, --target VERSION to migrate to a specific version, --dry-run to preview without applying.

flaxon schedule

Runs your app's scheduled tasks (see flaxon.tasks).

flaxon schedule app:app --once

--once runs due tasks a single time and exits, instead of running continuously.

flaxon worker

Starts a background worker process to consume tasks from a queue (see flaxon.tasks).

flaxon worker app:app --concurrency 4 --queue default

--concurrency N sets how many tasks run at once, --queue NAME picks which queue to consume from.

flaxon --version

Prints the installed version.

$ flaxon --version
Flaxon 0.1.4

Updated starter workflow (next release)

The changes in Flaxon PR #34 require a release containing that PR. They are not included in the published 0.3.0 package. Both the full-stack and basic starters generate requirements.txt instead of pyproject.toml.

After creating the project, use its interpreter directly; activation is optional:

cd my-project
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python management.py check
.venv/bin/python management.py runserver

On Windows PowerShell:

Set-Location -LiteralPath my-project
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe management.py check
.\.venv\Scripts\python.exe management.py runserver

Run the migrations and administrator setup from the main walkthrough before using the database or Admin. The basic template uses python -m flaxon run app:app --reload instead of management.py.

Slow or interrupted creation

Files appear before setup finishes. Wait for the completion message: Python still needs to create .venv and install its bundled pip. The updated CLI shows these as separate phases, with elapsed progress and a 120-second timeout per phase. Application dependencies download only when you run pip install -r requirements.txt. Disk speed and antivirus scanning may affect environment setup; the CLI cannot guarantee an instant finish.

If setup times out or you cancel it, keep your project files and retry from the parent directory:

python -m flaxon new my-project --resume-venv --venv-timeout 300

Recovery preserves edited sources, also supports older projects containing pyproject.toml, and prints the appropriate install command. Ctrl+C stops the setup process tree. For a new project using an environment you manage yourself:

flaxon new my-project --no-venv

The updated starter disables automatic background type checking; run python management.py typecheck explicitly when needed.

new and version commands do not import the current project's custom CLI module or application. Other commands still discover custom commands once. Keep flaxon_cli.py limited to command declarations; import expensive services inside a command handler.