---
name: prism-cli
description: Prism CLI for generating full-stack CRUD apps from Pydantic specs. Use when creating projects, generating code, running migrations, managing Docker, deploying, or working with Prism specifications.
---

Prism (`prisme` on PyPI) is a code generation framework that produces full-stack CRUD applications from Pydantic model specifications. Python 3.13+.

Always prefix commands with `uv run` (e.g., `uv run prisme generate`).

## Core Workflow

```bash
uv run prisme create my-app         # 1. Create project
# Edit specs/models.py              # 2. Define models
uv run prisme generate              # 3. Generate code
uv run prisme install               # 4. Install deps
uv run prisme db init               # 5. Init migrations
uv run prisme db migrate            # 6. Run migrations
uv run prisme dev                   # 7. Start dev servers
```

## Key Commands

- `prisme create <name>` — Create a new project
- `prisme generate` — Generate code from specs (`--dry-run` to preview)
- `prisme validate` — Validate spec files
- `prisme dev` — Start dev servers (backend, frontend, MCP)
- `prisme install` — Install dependencies
- `prisme test` — Run tests
- `prisme db init|migrate|reset|seed` — Database operations
- `prisme docker init|logs|shell|down|reset-db|backup-db|restore-db|init-prod|build-prod` — Docker
- `prisme check` — Verify project consistency with the spec
- `prisme diff [SPEC_PATH]` — Show what would change on regenerate (`--summary`, `--file`)
- `prisme review list|diff|show|mark-reviewed|clear|restore` — Code override review
- `prisme deploy init|plan|apply|destroy|ssh|logs|status|ssl` — Hetzner/Terraform deployment
- `prisme ci init|status|validate|add-docker` — CI/CD pipelines
- `prisme devcontainer up|down|shell|logs|status|list|exec|test|migrate|url|generate` — Dev containers
- `prisme proxy status|diagnose|restart` — Reverse proxy
- `prisme auth login|logout|status` — Authentication
- `prisme subdomain list|claim|activate|status|release` — Managed subdomains
- `prisme projects list|down-all` — Multi-project management

For the full command reference with descriptions, see [commands.md](commands.md).

## Specification Model (v2)

Projects are defined via a `StackSpec` in `specs/models.py`. Exposure is controlled at the
project level (`specs/project.py`) and per-model via `expose`, `operations`, and override models:

```python
from prisme import (
    StackSpec, ModelSpec, FieldSpec, FieldType,
    FrontendOverrides, DeliveryOverrides,
)

spec = StackSpec(
    name="my-app",
    models=[
        ModelSpec(
            name="Customer",
            fields=[
                FieldSpec(name="name", type=FieldType.STRING, required=True),
                FieldSpec(name="email", type=FieldType.STRING, required=True),
            ],
            # expose=True by default, operations=["create","read","update","delete","list"]
            delivery_overrides=DeliveryOverrides(rest_tags=["customers"]),
            frontend_overrides=FrontendOverrides(nav_label="Customers"),
        ),
    ],
)
```

### Field Types

`STRING`, `TEXT`, `INTEGER`, `FLOAT`, `DECIMAL`, `BOOLEAN`, `DATETIME`, `DATE`, `TIME`, `UUID`, `JSON`, `ENUM`, `FOREIGN_KEY`

### Relationships

```python
from prisme import RelationshipSpec

ModelSpec(
    name="Order",
    fields=[
        FieldSpec(name="customer_id", type=FieldType.FOREIGN_KEY, references="Customer"),
    ],
    relationships=[
        RelationshipSpec(
            name="customer",
            target_model="Customer",
            type="many_to_one",
            back_populates="orders",
        ),
    ],
)
```

## Generated Project Structure

```
project/
├── prisme.toml               # Configuration
├── specs/models.py            # Model specifications
├── specs/project.py           # Project-level configuration
├── packages/
│   ├── backend/src/<pkg>/
│   │   ├── models/           # SQLAlchemy models
│   │   ├── schemas/          # Pydantic schemas (generated, do not edit)
│   │   ├── services/
│   │   │   ├── _generated/   # Generated base classes (do not edit)
│   │   │   └── *_service.py  # User extension files (safe to edit)
│   │   ├── api/rest/         # REST endpoints
│   │   ├── api/graphql/      # GraphQL types
│   │   └── mcp_server/       # MCP tools
│   └── frontend/src/
│       ├── types/            # TypeScript types (generated, do not edit)
│       ├── components/
│       │   ├── _generated/   # Generated components (do not edit)
│       │   └── *.tsx         # User extension files (safe to edit)
│       ├── hooks/
│       ├── pages/
│       └── graphql/
```

## Key Rules

- **Never edit** files in `_generated/`, `schemas/`, or `types/` — they are regenerated
- **Safe to edit**: service extension files, component extension files, anything outside `_generated/`
- After changing specs, run `prisme generate` then `prisme db migrate` if schema changed
- Use `prisme generate --dry-run` to preview changes before applying

## Protected Regions

Generated files that use `ALWAYS_OVERWRITE` strategy support protected regions for inline customizations. Code between these markers is preserved during regeneration.

**Python:**
```python
# PRISM:PROTECTED:START - Custom Imports
from mylib import helper
# PRISM:PROTECTED:END
```

**TypeScript/JSX:**
```tsx
{/* PRISM:PROTECTED:START - Custom Providers */}
<MyCustomProvider>
  <RouterProvider router={router} />
</MyCustomProvider>
{/* PRISM:PROTECTED:END */}
```

Use protected regions for:
- Custom imports in generated files
- Adding providers/wrappers in generated React components
- Pre/post processing hooks in generated services
- Any inline customization in files that get regenerated
