CLI Reference

The pyxle CLI manages Pyxle projects from scaffolding to production.

Global options

pyxle init

Create a new Pyxle project.

pyxle init <name> [options]

pyxle init is interactive: when stdin is a terminal and no flag pins the choice, it walks you through arrow-key selections — Tailwind CSS, shadcn/ui (only if Tailwind is enabled), and whether to customize the default import alias (@/*; the value input appears only if you say yes). When stdin is not a terminal (CI, pipes), it never prompts — it uses the flags and defaults below. The target is validated before the first question, so an unusable name or an occupied directory never costs you a set of answers.

Examples:

pyxle init my-app                          # interactive prompts
pyxle init my-app --yes                     # accept defaults (no Tailwind)
pyxle init my-app --tailwind --no-shadcn    # Tailwind only, no prompts
pyxle init my-app --shadcn                  # shadcn/ui (implies Tailwind)
pyxle init .                                # scaffold into an empty current dir
pyxle init my-app --force --install

pyxle install

Install Python and Node.js dependencies.

pyxle install [directory] [options]

Examples:

pyxle install
pyxle install --no-python    # Node only
pyxle install ./my-app
pyxle install --break-system-packages   # PEP 668 system Python, no venv

Outside a virtualenv, pyxle install warns about PEP 668 ("externally-managed-environment") and recommends creating a venv first; pass --break-system-packages to install anyway.

pip and npm output is captured, not printed — a successful install shows only the step lines and the result:

▶️  Python dependencies — /usr/bin/python -m pip install -r requirements.txt
▶️  Node dependencies — npm install
✅ Dependencies installed.

Nothing is hidden that you need. A failure replays everything the installer said, verbatim, before the error, and pyxle -v install streams its output live.

pyxle dev

Start the development server with hot reload.

pyxle dev [directory] [options]

Examples:

pyxle dev
pyxle dev --host 0.0.0.0 --port 3000
pyxle dev --no-tailwind --ssr-workers 4
pyxle dev ./my-app --print-config
pyxle dev --verbose             # troubleshoot: full Vite + debug output

If the port is taken. pyxle dev and pyxle serve check the port before they start anything — before Vite, before npm install, and before a build — so an occupied port costs you a message rather than a build:

❌ Port 8000 is already in use, so pyxle dev cannot start.

Something is already listening on 127.0.0.1:8000 — most often a pyxle dev from
an earlier session that is still running, or another application using the same
port.

Start on a free port:   pyxle dev --port 8001
See what is holding it: lsof -i :8000

The suggested port is one that was free when the message was written; nothing is reserved. Note that only the Vite port moves on its own (Vite port 5173 in use; retrying on 5174) — the port you asked for is never silently changed, because a server quietly listening somewhere other than where you pointed your browser is worse than one that did not start.

What it does:

1. Loads configuration from pyxle.config.json + environment variables + CLI flags
2. Compiles .pyxl files into Python and JSX modules
3. Starts the Vite dev server for React hot reload (Tailwind v4 compiles here via the @tailwindcss/vite plugin)
4. Starts the legacy Tailwind v3 watcher only if a hand-written tailwind.config.* is detected
5. Starts the Starlette ASGI server
6. Watches for file changes and recompiles automatically

Opening the page from another device. --host 0.0.0.0 makes the dev server answer on your machine's network address, and the startup banner prints the Network: URL to use. Pyxle widens the whole dev server to match: Vite binds the same address, and both servers accept the private-network origins that address implies — the JavaScript modules, the hot-reload socket and the error overlay all reach that browser. Open the printed URL; a page opened at some other address (a hostname, a public IP, an https tunnel) is served but cannot load its modules, and the terminal says so on the first request. See which browsers the dev server trusts.

Console output. By default pyxle dev prints a clean, curated console — a startup summary (the local URL, the Vite URL, the route count, the Studio URL, and the total "ready in X ms"), a concise one-line notice per incremental rebuild (Rebuilt … in X ms), and any warnings or errors. The raw line-by-line Vite firehose and debug-level internals are hidden. Pass --verbose (or -v, or the global pyxle -v dev) to restore the full output when troubleshooting. Genuine signal — errors, warnings, the URLs, and rebuild success/failure — is always shown, at every verbosity.

Server logs in the browser console (dev only). While pyxle dev is running, your server-side logging output (from loaders, actions, and your own modules) is forwarded to the browser devtools console, prefixed [pyxle:server] and mapped to the matching console method (info → console.info, warning → console.warn, error → console.error). The same records also print in the terminal, so you can follow server logs from whichever window you are already in. By default only INFO and above from your own loggers are forwarded; --verbose additionally forwards DEBUG records and the framework's own internal loggers to the browser. This is strictly a development feature — it never runs under pyxle serve and never appears in the production bundle.

The idiomatic Python logger works as-is inside a .pyxl page:

import logging

log = logging.getLogger(__name__)

@server
async def load_dashboard(request):
    log.info("loading dashboard")
    ...

[pyxle:server pages/dashboard.pyxl] loading dashboard

A page's records are labelled with the .pyxl file that emitted them rather than the module name it is compiled under. A logger you name yourself keeps that name: logging.getLogger("shopapp") prints as [pyxle:server shopapp].

pyxle studio

Run the dev server and open the Pyxle Studio dashboard.

pyxle studio [directory] [options]

pyxle studio runs the same development server as pyxle dev — Studio is part of it, served at /__pyxle/studio — and opens your browser on the dashboard once the server is ready. Debug mode is forced on (Studio is dev-only), and the dashboard is enabled for this run even when the config sets "studio": false.

Examples:

pyxle studio                     # dev server + dashboard in the browser
pyxle studio --no-open           # dashboard enabled, but don't launch a browser
pyxle studio --inspect           # dashboard + debugger in one command
pyxle studio ./my-app --port 3000

pyxle build

Build production-ready assets.

pyxle build [directory] [options]

Examples:

pyxle build
pyxle build --analyze
pyxle build --out-dir ./output --incremental
pyxle build --static

pyxle serve

Serve a production build (without Vite).

pyxle serve [directory] [options]

Examples:

pyxle serve
pyxle serve --host 0.0.0.0 --port 8000 --skip-build
pyxle serve --ssr-workers 4
pyxle serve --workers $(nproc)   # one server process per CPU core

With --workers N (N > 1), Pyxle serves the build across N uvicorn worker processes. Each is an independent server with its own SSR pool, so --ssr-workers applies per worker (total render processes = workers × ssr-workers). See the deployment guide for sizing guidance.

pyxle check

Validate .pyxl files, configuration, and dependencies without starting the server. Each .pyxl file is checked at four levels:

• Python syntax (via ast) and Pyxle structural rules (loader/action shape, HEAD, …).
• Python semantics (via pyflakes): undefined names — e.g. a symbol you raise but never imported — unused imports, redefinitions. Compiler-injected runtime names (server, action, LoaderError, ActionError, …) are recognized, so the idiomatic patterns never read as undefined.
• JSX syntax (via Babel): unclosed tags/expressions, mismatched braces, TypeScript in a client block, and duplicate export default (which Babel accepts but the build rejects).
• @action signatures: an action that asks for a request body it never described — async def bump(request, payload) with no annotation on payload — is reported here rather than failing the first time someone triggers it. This is read off the parsed source, so check still never imports your module. An annotated body parameter is not flagged: whether Pydantic is installed is a property of the environment you deploy into, and pyxle openapi and the dev server answer that one.

As of 0.7.0 the JSX level works out of the box — pyxle-langkit, which provides the Babel-based checker, ships with the framework. On earlier versions it required the [langkit] extra (pip install 'pyxle-framework[langkit]'); without it, the JSX check reported itself unavailable.

What a green check proves — and what it doesn't. pyxle check is a static gate: it validates .pyxl syntax, Python semantics, and JSX syntax. It does not render your pages, so a mistake that only exists at runtime — a component reading data.posts when the loader returns {"items": ...}, a loader whose query fails against the real database — surfaces when the page renders, not here. Treat a clean check as "this compiles"; loading the page under pyxle dev (or a test that requests it) remains the runtime proof.

pyxle check [directory] [options]

Errors vs warnings

Findings are split by whether the code will actually break when it runs.

A semantic rule Pyxle does not recognise — one added by a future pyflakes — is reported as a warning, so upgrading a dependency can never turn into a surprise deploy blocker. This is what lets the deployment checklist gate a release on pyxle check: a leftover import json will not stop a deploy, an unresolved reference will.

Example output:

ℹ️  Checked 12 .pyxl file(s) in my-app/
✅ All checks passed

Findings are reported per file as [section] line N: message, with the file path on the next line (every file is checked, so one broken file never aborts the scan). Warnings print first, then errors:

ℹ️  Checked 12 .pyxl file(s) in my-app/
  warning: [python] line 3: 'json' imported but unused
    --> pages/index.pyxl
  error: [python] line 15: @server function must be async
    --> pages/index.pyxl
  error: [jsx] line 8:10: Unterminated JSX contents
    --> pages/settings.pyxl
❌ Check failed with 2 error(s) (1 warning(s))

Exit code is 0 when no error is found (warnings alone do not fail the command), 1 otherwise.

Every line number in a finding is a line of the .pyxl file — including a second one named inside the message, such as the [ a mismatched ) should have closed or the earlier binding a redefinition shadows:

  error: [python] line 11: closing parenthesis ')' does not match opening parenthesis '[' on line 8
    --> pages/products.pyxl
  warning: [python] line 9: import 'os' from line 7 shadowed by loop variable
    --> pages/products.pyxl

The checkers behind these levels each see one extracted half of your file and number their findings from the start of it; Pyxle translates those coordinates back to the file you are editing before printing them.

pyxle typecheck

Run TypeScript type-checking on compiled JSX output.

pyxle typecheck [directory] [options]

Requires typescript in your devDependencies. Runs tsc --noEmit against the compiled JSX in .pyxle-build/client/.

pyxle routes

Display the route table for your project.

pyxle routes [directory] [options]

Example output:

ℹ️  Routes for my-app/

ℹ️    Pages:
▶️  / — index.pyxl  [loader=load_home]
▶️  /about — about.pyxl
▶️  /blog/{slug} — blog/[slug].pyxl  [loader=load_post]

ℹ️    API Routes:
▶️  /api/pulse — api/pulse.py

ℹ️    Special Files (no URL of their own):
▶️  error boundary — error.pyxl  [covers /]
▶️  404 page — not-found.pyxl  [covers /]
▶️  loading fallback — blog/loading.pyxl  [covers /blog/*]

✅ 4 route(s) found

error.pyxl, not-found.pyxl and loading.pyxl are compiled but serve no URL of their own, so they are listed by what they do and by the URL subtree they cover — not under a path you could visit. They are not counted in the route total.

Use --json for machine-readable output; it lists page and API routes only. Under --json the array is the only thing written to stdout and messages go to stderr, so pyxle routes --json > routes.json captures valid JSON or an empty file. The human table above is not data and stays on stdout.

pyxle openapi

Generate an OpenAPI 3.1 document from your @action request models. For every action that declares a Pydantic body parameter, Pyxle emits a POST operation with the model's JSON Schema as the request body and a structured 422 validation response; actions without a model get a permissive object body.

pyxle openapi [directory] [options]

# Print to stdout
pyxle openapi

# Redirect or pipe it — stdout carries the document and nothing else
pyxle openapi > openapi.json
pyxle openapi | jq '.paths'

# Write a file with custom metadata
pyxle openapi --out openapi.json --title "Acme API" --api-version 2.0.0

The document is the only thing written to stdout; progress and errors go to stderr. So a redirect captures valid JSON or an empty file — never a document with a message in it — and a failure is still visible in the terminal. The same applies to pyxle routes --json.

The schema is derived from runtime introspection of the compiled action modules, so it always matches what the dispatcher actually validates.

Pydantic is only needed for the actions that actually declare a model body. A project whose actions take no body — or which has no actions yet — generates its document without the [pydantic] extra installed, and an empty paths object is the correct answer for a project with no actions. The command exits with an error if an action declares a model body and Pydantic isn't installed (pip install "pyxle-framework[pydantic]"; the message names the action and its file), or if a page module can't be imported.