Skip to content

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 --locked
puerto --help

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.

List entities and use cases defined in puerto.toml.

puerto listar

See the guide: puerto.toml.

Validate puerto.toml (field types, names, entity consistency).

puerto validar

See the guide: What puerto validar checks.

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.

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.

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>=, comma-separated (e.g. crear_producto=admin,borrar_producto=admin) — #[requiere_rol] on the handler

See the guide: Entities and fields.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.