CLI
Generated from the --help of puerto 0.21.0, so it says exactly what the CLI says.
Every command that writes Rust ends by running cargo fmt on the project.
cargo install puerto --lockedpuerto --helppuerto nuevo
Section titled “puerto nuevo”Scaffold a new Puerto project.
puerto nuevo [OPTIONS]| Option | |
|---|---|
--nombre <NAME> |
Project name (skips interactive prompt) |
--db |
Include database support (SQLx + Postgres) (skips interactive prompt) |
--sin-db |
Explicitly skip database support without prompting |
--sin-demo |
Skip the Saludo demo entity (creates an empty project) |
--sin-web |
Skip the web frontend (web/: React + daisyUI on Bun) |
--eventos <EVENTS> |
Domain events (needs --db): every write records an event in an outbox, relayed through this transport. Possible values: db, kafka. |
--auth <AUTH> |
Auth: oidc verifies an OpenID Connect provider’s tokens (Auth0, Keycloak — Keycloak runs in docker-compose.yml for development); local keeps accounts and sessions in the project’s database (needs --db). Possible values: oidc, local. |
--destino <DESTINATION> |
Directory where the project will be created (defaults to current directory) |
See the guide: Quick start.
puerto listar
Section titled “puerto listar”List entities and use cases defined in puerto.toml.
puerto listarSee the guide: puerto.toml.
puerto validar
Section titled “puerto validar”Validate puerto.toml (field types, names, entity consistency).
puerto validarSee the guide: What puerto validar checks.
puerto completions
Section titled “puerto completions”Print shell completion script.
puerto completions <SHELL>| Argument | |
|---|---|
<SHELL> |
Shell to generate completions for (bash, zsh, fish, powershell). Possible values: bash, elvish, fish, powershell, zsh. |
Generators
Section titled “Generators”Every generator reads and updates puerto.toml, refuses to overwrite files that already
exist (scaffold --forzar and web --forzar are the explicit exceptions) and prints the next
step.
puerto generar scaffold
Section titled “puerto generar scaffold”Scaffold all DDD layers for a new entity (db and CRUD inferred from puerto.toml).
puerto generar scaffold [OPTIONS] <NAME> [-- <FIELDS>...]| Argument | |
|---|---|
<NAME> |
Entity name in PascalCase (e.g. Producto, LineaPedido) |
[FIELDS]... |
Fields after – separator. Primitives: titulo:String precio:i64! nota:opt:String etiquetas:vec:String Value Objects: nombre:Nombre:String edad:Edad:i64 estado:Estado:enum:Activo/Inactivo apodo:Apodo:opt:String Shared VO (type inferred from puerto.toml): email:Email |
| Option | |
|---|---|
--forzar |
Overwrite an already-generated entity, discarding hand-written changes in its files |
--publico <PUBLIC> |
Auth projects: use cases whose routes need no token, comma-separated (e.g. listar_productos,obtener_producto). Every other route takes auth: BearerAuth |
--rol <ROLE> |
Auth projects: a role a route requires, <use_case>=#[requiere_rol] on the handler |
See the guide: Entities and fields.
puerto generar caso-de-uso
Section titled “puerto generar caso-de-uso”Add a use case to an existing entity.
puerto generar caso-de-uso <ENTITY> <ACTION>| Argument | |
|---|---|
<ENTITY> |
Entity name in PascalCase (e.g. Producto) |
<ACTION> |
Use case action in snake_case (e.g. publicar_producto) |
See the guide: Use cases.
puerto generar objeto-valor
Section titled “puerto generar objeto-valor”Declare a shared value object in puerto.toml (reusable across entities).
puerto generar objeto-valor <NAME> <INNER_TYPE>| Argument | |
|---|---|
<NAME> |
Value object name in PascalCase (e.g. Email, Dinero) |
<INNER_TYPE> |
Inner primitive type: String, i64, bool, f64, Uuid, DateTime |
See the guide: Value objects.
puerto generar migracion
Section titled “puerto generar migracion”Create a new SQLx migration file.
puerto generar migracion <NAME>| Argument | |
|---|---|
<NAME> |
Migration name in snake_case (e.g. anadir_stock_a_productos) |
See the guide: Database and migrations.
puerto generar evento
Section titled “puerto generar evento”Declare a custom domain event of a CRUD entity and regenerate its events.rs (projects created with –eventos).
puerto generar evento <ENTITY> <NAME>| Argument | |
|---|---|
<ENTITY> |
Entity name in PascalCase (e.g. Producto) |
<NAME> |
Event type in snake_case, past tense (e.g. producto_publicado) |
See the guide: Domain events.
puerto generar consumidor
Section titled “puerto generar consumidor”Add a consumer to the worker: an event handler, its tests and its registry entry (projects created with –eventos).
puerto generar consumidor --tras <ON> <NAME>| Argument | |
|---|---|
<NAME> |
Consumer name in snake_case (e.g. avisar_producto_nuevo) |
| Option | |
|---|---|
--tras <ON> |
The event types it handles, comma-separated (e.g. producto_creado,producto_publicado) |
See the guide: Consumers.
puerto generar correo
Section titled “puerto generar correo”Add a mail: its port, its template implementation and its templates (asunto.txt, cuerpo.html, cuerpo.txt). The first one also adds Mailpit and SMTP_URL / MAIL_FROM to .env.
puerto generar correo [OPTIONS] <NAME> [-- <FIELDS>...]| Argument | |
|---|---|
<NAME> |
Mail name in snake_case (e.g. bienvenida, pedido_enviado) |
[FIELDS]... |
The values its text shows, after –: nombre:String plazas:i64 plan:opt:String. Primitives and opt:<type> only; the recipient para is always there. None: nombre:String |
| Option | |
|---|---|
--tras <ON> |
Projects created with –eventos: the worker sends the mail on these event types, comma-separated (e.g. cliente_creado). Its fields come from the events’ snapshots |
--para <TO> |
With –tras: the String field of the snapshot that holds the recipient (e.g. email) |
See the guide: Mail.
puerto generar web
Section titled “puerto generar web”Scaffold only the frontend slice of an existing CRUD entity (web projects; regenerates web/src/presentation/core/generated/).
puerto generar web [OPTIONS] <NAME>| Argument | |
|---|---|
<NAME> |
Entity name in PascalCase (e.g. Producto) |
| Option | |
|---|---|
--forzar |
Overwrite the entity’s existing frontend files, discarding hand-written changes |
See the guide: The web frontend.
puerto generar dominio
Section titled “puerto generar dominio”Scaffold only the domain layer for a new entity (domain-first workflow).
puerto generar dominio <NAME> [-- <FIELDS>...]| Argument | |
|---|---|
<NAME> |
Entity name in PascalCase (e.g. Producto, LineaPedido) |
[FIELDS]... |
Fields after – separator. Same syntax as generar scaffold. They are written to puerto.toml, so generar aplicacion/repositorio/presentacion pick them up |
See the guide: Layer by layer.
puerto generar aplicacion
Section titled “puerto generar aplicacion”Scaffold only the application layer for an existing entity.
puerto generar aplicacion <NAME>| Argument | |
|---|---|
<NAME> |
Entity name in PascalCase (e.g. Producto) |
See the guide: Layer by layer.
puerto generar repositorio
Section titled “puerto generar repositorio”Scaffold only the repository (infrastructure) layer for an existing entity.
puerto generar repositorio <NAME>| Argument | |
|---|---|
<NAME> |
Entity name in PascalCase (e.g. Producto) |
See the guide: Layer by layer.
puerto generar presentacion
Section titled “puerto generar presentacion”Scaffold only the presentation layer for an existing entity (regenerates bootstrap.rs).
puerto generar presentacion <NAME>| Argument | |
|---|---|
<NAME> |
Entity name in PascalCase (e.g. Producto) |
See the guide: Layer by layer.
puerto generar bootstrap
Section titled “puerto generar bootstrap”Regenerate the wiring (presentacion/cableado, presentacion/api/src/generado/bootstrap.rs) from puerto.toml.
puerto generar bootstrap [OPTIONS]| Option | |
|---|---|
--permitir-faltantes |
Write the file even when puerto.toml declares entities whose code is not on disk |
See the guide: When the wiring is out of date.
puerto generar snippets
Section titled “puerto generar snippets”Write IDE snippet files (.zed/snippets/rust.json, .vscode/puerto.code-snippets).
puerto generar snippets [OPTIONS]| Option | |
|---|---|
--ide <IDE> |
Target IDE: zed or vscode (default: both) |
See the guide: IDE snippets.