Skip to content

Commands ​

Use uv run smpy ... from your app to run its installed CLI and plugins. The scaffolded Makefile provides convenient aliases for the same commands. Install the scaffolder with uv tool install simple_module_cli (upgrade with uv tool upgrade simple_module_cli) before creating your first app.

uv run smpy CLI ​

bash
uv run smpy --help

Scaffolders ​

CommandWhat
uv run smpy new <name>Scaffold a new app at ./<name>. Interactive by default; pass --yes for defaults, --preset minimal|standard|full, --with mod1,mod2 for extras, --db sqlite|postgres, --tenancy, --flat (no modules/ dir).
uv run smpy create-module <name>Scaffold a module at ./simple_module_<name> (or --dest <path>). Inside an app workspace, also wire it into the host, sync dependencies and generate frontend files.
uv run smpy create-host <name>Scaffold just a host project (no sample module). Useful when you want a minimal shell that consumes published modules.

Installing modules ​

CommandWhat
uv run smpy add <spec>Add a module dependency and wire it up. <spec> is a PyPI requirement, a git+URL[@ref][#subdirectory=dir], or a local path. Writes pyproject.toml, then runs uv sync. If the host has a client_app, it runs gen-pages, installs JS dependencies declared by modules via sync-js-deps with --save=false, and skips gen-i18n when the i18n package is absent. Use --no-sync to skip these steps. Workspace apps sync from the app root with uv sync --all-packages.
uv run smpy update [name]Update framework/module pins from PyPI and git across the app workspace, then sync Python and npm lockfiles and run generation. Omit the name for all pins; --dry-run writes and installs nothing.

uv run smpy add handles a repo containing several modules: --module a,b picks specific dist names and --all takes every module it finds.

Modules from one repo move in lockstep — one repo, one ref. uv run smpy update takes every module sourced from the same URL to the same new tag, which must be a v* semver tag satisfying every sibling's declared dependency range. Version bumps preserve explicit ceilings, excluded releases, and the implicit upper bound of ~= constraints, so later updates still respect the original policy. Mixing tags from one source tree is how you end up with a module built against a sibling it was never shipped with. Branch-pinned sources re-lock to the newest SHA (dev mode), rev-pinned sources are left alone, and workspace/path/URL sources stay unchanged. PyPI pins keep their operator, ceilings, extras and markers. Optional dependencies and dependency groups are included. --include-pre includes PyPI pre-releases; --loosen rewrites PyPI constraints to >=<latest>.

Git tag updates also advance the dependency's version floor, preserving its extras and environment marker. For example, updating to v0.2.0 changes simple_module_blog[s3]>=0.1,<1.0; python_version >= "3.12" to simple_module_blog[s3]>=0.2.0,<1.0; python_version >= "3.12".

Both take --path to point at a project root or pyproject.toml other than the cwd. uv run smpy add takes --yes to fail rather than prompt, which is what you want in CI.

uv run smpy update updates @simple-module-py/* npm pins to the selected core release when published on npm. It runs uv sync (workspace apps: uv sync --all-packages from the app root), npm install where the frontend lives, then uv run smpy gen. Python-only hosts skip the frontend steps. Installation failures stop the command; fix the error and rerun it. uv run smpy package-update forwards to uv run smpy update as a deprecated alias, removed in 0.0.50.

Authoring a module ​

After creating a workspace module, the remaining step is its migration:

bash
uv run smpy migrations new orders -m "init"
# Review the generated revision before applying it.
make migrate
# Restart make dev to discover the module.

migrations new resolves the host's Alembic config in either layout. It uses --head orders@head when that label exists, or creates a first root with --head base --branch-label orders. Autogenerate compares all installed metadata; review the revision for unrelated schema drift. Applying uses upgrade heads. A branch label is a named Alembic target; it does not isolate rollbacks.

Run these from inside a module package directory:

CommandWhat
uv run smpy module verifyBuild this module's frontend inside a throwaway scaffolded host — catches "works in the monorepo, breaks as a wheel" before you publish.
uv run smpy module buildBundle <pkg>/assets_src/ into <pkg>/static/dist/ for static_mounts().

Both cache the scratch host under .smpy/verify-host; pass --fresh to rebuild it from scratch.

Maintenance ​

CommandWhat
uv run smpy skills add|list|updateInstall or update the bundled agent skills under .claude/skills/ for use with Claude Code.

Module-contributed plugins ​

When a module declares a simple_module_cli.cli_plugins entry point, the CLI mounts it as a sm <name> ... subgroup. The bundled modules contribute:

CommandFromWhat
uv run smpy gensimple_module_hostingRun pages, i18n keys, module JS dep sync and API types. Per-stage content hashes and output checks in the local .smpy/gen.json cache skip unchanged work without touching files. API generation covers local modules already carrying pages/api.generated.ts; use uv run smpy openapi gen-types --module <pkg> to opt in.
uv run smpy devsimple_module_hostingGenerate first, then run API and Vite together. API defaults to 8000 (--port); Vite uses the first free port from 5050 (--vite-port pins it). Python reads dotenv and passes the selected SM_VITE_DEV_URL to both children. Ctrl-C, SIGTERM or either child exiting stops both owned process groups.
uv run smpy host gen-pagessimple_module_hostingRegenerate client_app/modules.{manifest.json,generated.ts,generated.css,assets.json} from the installed modules. Run when you add or remove pages or assets.
uv run smpy host gen-i18nsimple_module_hostingRegenerate keys.generated.ts and generated-resources.ts into the installed @simple-module-py/i18n/src directory (or packages/i18n/src in the framework repo) without booting the app. Fails if neither exists unless --skip-if-missing is set.
uv run smpy host sync-js-depssimple_module_hostingInstall module-declared JS deps into the host. Module-root npm workspace manifests are installed by npm automatically; dependency-only manifests inside Python packages need this sync even for editable installs.
uv run smpy settings import-from-envsimple_module_settingsOne-shot migration: read every SM_<MODULE>_* env var and seed it as a SYSTEM-scope row in the DB-backed settings store. Idempotent.

uv run smpy users create-admin is contributed by the users module as a uv run smpy users subcommand:

bash
uv run smpy users create-admin --email admin@example.com

Scaffolded-app Makefile ​

uv run smpy new defaults to a workspace layout: the app root owns the uv and npm workspaces and the Makefile; the host lives in host/, with its frontend in host/client_app/ and local modules under modules/. uv run smpy new --flat and uv run smpy create-host use a flat layout: the host is at the app root and its frontend is in client_app/.

Run make from the app root in either layout. The current templates use uv run smpy gen for generation and uv run smpy dev to run API and Vite together:

CommandFlat layoutWorkspace layout
make installuv sync, cd client_app && npm install, then make gen.uv sync --all-packages, root npm install, then make gen.
make dev-apiuv run uvicorn main:app --reload --reload-include '*locales/*.json' --port $(API_PORT).Runs uvicorn from host/, also watching . and ../modules with --reload-dir.
make dev-uicd client_app && npm run dev.Root npm run dev, which delegates to the host/client_app npm workspace.
make migrateuv run alembic upgrade heads.uv run --project host alembic -c host/alembic.ini upgrade heads.
make buildmake gen, then cd client_app && npm run build.make gen, then root npm run build (delegates to host/client_app).
JS dependency syncmake sync-js-deps.make sync-module-deps.

Both JS dependency sync targets call uv run smpy host sync-js-deps directly. Root module npm manifests are installed by npm workspaces; manifests inside Python packages need this sync even for editable installs. Both migration targets apply all branch heads (upgrade heads, plural).

The remaining targets have the same purpose in both layouts:

CommandWhat
make installuv sync + cd client_app && npm install + uv run smpy gen. Workspace apps use uv sync --all-packages and root npm install. Re-runs are safe.
make devRuns uv run smpy dev. Pass options with make dev ARGS="--port 8010 --vite-port 5201". Vite auto-selects a free port when omitted.
make migrateApply all branch heads using the layout-specific command above. Idempotent.
make builduv run smpy gen, then cd client_app && npm run build (root npm run build in a workspace). Produces the production frontend bundle.
make genSame incremental pipeline as uv run smpy gen. Install, dev, build and module verify call it automatically. Generation errors stop startup/build.
make gen-pagesRegenerate modules.manifest.json, modules.generated.ts, modules.generated.css and modules.assets.json in the host's frontend directory. Install, dev and build include this stage via uv run smpy gen. Same effect as uv run smpy host gen-pages.
make sync-js-deps (flat) / make sync-module-deps (workspace)Install module-declared JS deps as described above. Same effect as uv run smpy host sync-js-deps.
make gen-i18nRegenerate keys.generated.ts and generated-resources.ts for typed t(keys.<ns>...) calls. Writes into the installed @simple-module-py/i18n/src, the first copy found in node_modules at the app root, then client_app/node_modules, then parent directories. Install, dev and build include this stage via uv run smpy gen. Same effect as uv run smpy host gen-i18n.
make doctorAlias for uv run smpy doctor. Run module diagnostics, including migration state and table coverage. Structural checks also run at development boot; production does not run that suite.
make killPrint stop guidance: Ctrl-C in the uv run smpy dev terminal, or send SIGTERM to its supervisor PID. No processes are searched for or killed by port/name.

If you included background_tasks in uv run smpy new, the scaffold appends worker, beat, and worker-docker targets that wrap the Celery commands — read your Makefile to see the exact invocations.

Routine ops without a target ​

The scaffolded Makefile intentionally doesn't wrap one-off things. Run them directly:

NeedCommand
New module migrationuv run smpy migrations new <module> -m "..."
Downgrade one revisionuv run alembic downgrade -1
Remove one module's schemaSee Removing one module's schema; <module>@base rolls back the whole chain beneath it
Single Python testuv run pytest path/to/test_file.py::test_name
Single JS testcd client_app && npx vitest run <path>
Format + lint Pythonuv run ruff format . && uv run ruff check .
Type-check Pythonuv run ty check
Format + lint JScd client_app && npx biome check .
Type-check JScd client_app && npx tsc --noEmit
Free stuck dev portsCtrl-C / SIGTERM the uv run smpy dev supervisor

Working on the framework itself ​

If you're contributing to simple_module_python — not consuming it — the framework repo's Makefile is bigger: it includes make new-module, make doctor, make lint, make test, make migration, make worker, make memray-run, make loadtest, etc. Those targets exist because the framework repo is a multi-package workspace, not because they're the user-facing surface. See the release playbook and the repo's Makefile for that flow.

Next steps ​

The individual generators remain available for explicit regeneration and CI. In the framework repo, ci-i18n-fresh and ci-api-types-fresh bypass the incremental cache and compare contents before/after generation, so stale committed files still fail. i18n output stays in the existing package location: its exports and type augmentation depend on those files; app-owned output needs a separate package integration change.

Released under the MIT License.