Skip to content

CLI Reference

Global Options

moltpy [OPTIONS] COMMAND [ARGS]...
Option Description
--version Show version and exit
--help Show help message and exit

moltpy new

Create a new FastAPI project.

moltpy new [OPTIONS]

Options

Option Short Description
--name -n Project name (snake_case). Required in non-interactive mode
--description -d Project description
--python-version -p Python version (default: 3.12)
--preset Use a preset (minimal, standard, full-stack, microservice)
--modules -m Comma-separated list of modules (overrides preset)
--target -t Target directory (default: ./)
--force Overwrite existing non-empty directory
--dry-run Preview files without writing
--skip-post-generation Skip uv sync, git init, and pre-commit install
--config-file -f Load configuration from JSON or YAML file
--no-interactive Skip interactive prompts
--template-dir Directory with custom templates that override built-ins
--refresh-modules Force re-fetch cached GitHub modules

Examples

# Interactive mode
moltpy new

# Non-interactive with preset
moltpy new --name my_api --preset standard --no-interactive

# Non-interactive with modules
moltpy new --name my_api --modules auth,database,docker --no-interactive

# Dry-run: preview without writing files
moltpy new --name my_api --preset standard --dry-run --no-interactive

# Force overwrite existing directory
moltpy new --name my_api --preset standard --force --no-interactive

# Skip post-generation hooks
moltpy new --name my_api --preset standard --skip-post-generation --no-interactive

# Generate from a JSON config file
moltpy new --config-file moltpy.json --no-interactive

# Generate from a YAML config file
moltpy new --config-file moltpy.yaml --no-interactive

# Config file with CLI overrides
moltpy new --config-file moltpy.yaml --name override_name --no-interactive

# With custom templates
moltpy new --name my_api --preset standard --template-dir ./my-templates --no-interactive

# With a GitHub module
moltpy new --name my_api --modules auth,github:user/repo#my-module --no-interactive

# Force re-fetch GitHub modules
moltpy new --name my_api --modules github:user/repo#my-module --refresh-modules --no-interactive

moltpy init-config

Generate a starter configuration file (YAML or JSON) that can be edited and reused with moltpy new --config-file.

moltpy init-config [OPTIONS]

Options

Option Short Description
--name -n Project name (default: my_project)
--preset Base preset to seed modules
--output -o Output file path (default: moltpy.yaml)

Examples

# Generate default config
moltpy init-config

# Generate config with a preset
moltpy init-config --preset standard

# Custom output path
moltpy init-config --preset full-stack --output team-config.yaml

# Generate JSON instead of YAML
moltpy init-config --output moltpy.json

The generated file includes: - All configuration fields with defaults - Inline comments explaining each option - A documented list of all available modules (when using YAML output)

moltpy preset

Manage project presets.

moltpy preset list

List all available presets (built-in + user-defined).

moltpy preset list

moltpy preset save

Save current configuration as a preset.

moltpy preset save [OPTIONS]
Option Short Description
--name -n Preset name (required)
--description -d Preset description
--modules -m Comma-separated module list (required)
--python-version -p Python version (default: 3.12)

moltpy preset delete

Delete a user-defined preset.

moltpy preset delete --name <preset_name>

Built-in presets cannot be deleted.

moltpy modules

Explore available modules.

moltpy modules list

List all available modules grouped by category.

moltpy modules list

moltpy modules info

Show detailed information about a module.

moltpy modules info <module_name>

moltpy generate resource

Scaffold a new CRUD resource in an existing MoltPy project.

moltpy generate resource <ModelName> [field:type ...]

Options

Option Description
--skip-alembic Skip Alembic migration generation
--dry-run Preview changes without writing files

Supported Field Types

CLI Type SQLAlchemy Pydantic Example
str String(255) str title:str
text Text str content:text
int Integer int count:int
bool Boolean bool is_active:bool
float Float float price:float
uuid UUID(as_uuid=True) UUID owner_id:uuid
datetime DateTime(timezone=True) datetime published_at:datetime
json JSON dict[str, Any] metadata:json

Examples

# Generate a Post resource with title, content, and publish flag
cd my-api
moltpy generate resource Post title:str content:text is_published:bool

# Preview without writing
moltpy generate resource Post title:str --dry-run

# Skip Alembic migration (run it manually later)
moltpy generate resource Post title:str --skip-alembic

# Generate a Comment resource with a foreign key reference
moltpy generate resource Comment body:text post_id:uuid

Generated Files

For moltpy generate resource Post title:str, the following files are created:

  • app/models/post.py — SQLAlchemy model
  • app/schemas/post.py — Pydantic schemas (Create, Update, Response)
  • app/routers/posts.py — FastAPI router with REST endpoints
  • app/services/post.py — Async CRUD service layer
  • tests/api/test_posts.py — pytest tests with TestClient

The command also: - Injects app.include_router(...) into app/main.py (or app/routers/v1/api.py if api_versioning is enabled) - Appends the model import to app/models/__init__.py - Runs alembic revision --autogenerate - Runs ruff format and ruff check --fix to ensure clean code

Limitations: No complex relationship() mappings are generated. Foreign key columns (for example, post_id:uuid) are created, but relationships must be added manually. No custom enums or appending to existing models.

Environment Variables

MoltPy respects the following environment variables:

Variable Description
moltpy_PRESETS_DIR Custom directory for user presets (default: ~/.config/moltpy/presets/)