nestrs CLI: scaffold and manage projects

The nestrs CLI is published to crates.io as nestrs-scaffold — the binary you run is nestrs-cli. It scaffolds new single-crate applications, generates source files, and runs a lightweight diagnostic against your toolchain and Cargo.toml. Unlike the Nest CLI, it stays entirely within Cargo-native workflows and does not add Node-style scripts, monorepo management, or library packaging.

Install

Install from crates.io

cargo install nestrs-scaffold

Verify the binary

nestrs-cli --help

The crates.io package is nestrs-scaffold because the name nestrs-cli is already taken. The installed binary is nestrs-cli in either case.

If you are working inside a clone of the nestrs repository, the workspace defines a Cargo alias so you can skip the global install:

cargo nestrs doctor
cargo nestrs generate resource items --transport rest --path src

This alias is configured in .cargo/config.toml as run -p nestrs-scaffold --bin nestrs-cli --.

Available commands

Command	Purpose
`nestrs-cli new <name>`	Create a new single-crate app with `Cargo.toml`, `src/main.rs`, starter module/controller, `.env`, `.env.example`, `Dockerfile`, `.gitignore`, and `README.md`.
`nestrs-cli generate` / `nestrs-cli g`	Generate resources, services, controllers, modules, DTOs, guards, pipes, filters, interceptors, strategies, resolvers, gateways, microservices, and transports.
`nestrs-cli db migrate …`	Create, apply, revert, and inspect SQL migrations (`add`, `run`, `revert`, `info`). Default backend `sqlx`; `--backend prisma` passes through to `npx prisma`.
`nestrs-cli db seed …`	Seed the database from a Cargo seed binary (`--bin`) or a transactional SQL file (`--seed-file`).
`nestrs-cli doctor`	Print `rustc` and `cargo` versions, scan `Cargo.toml` for nestrs feature flags, and heuristically check `src/*/.rs` for common misconfigurations.
`nestrs-cli repl …`	Static DI graph explorer (`graph` / `routes` / `providers` / `dtos`) plus `repl live --url` against a running admin sidecar (`GET /__nestrs/providers` + `/routes`; bearer header; curl `--` before URL).

The db family ships behind the db Cargo feature (it pulls in sqlx and tokio as CLI dependencies). Install it with:

cargo install nestrs-scaffold --features db

Without the feature, nestrs-cli db … fails with a clear message instead of producing a half-built binary.

nestrs-cli db

nestrs-cli db is the migrations + seeding runner. It works on plain SQL migration files — there is no DDL-diff engine (synchronize) or entity auto-discovery; those belong to full ORMs.

nestrs-cli db [--backend sqlx|prisma] migrate add <name> [--reversible] [--path <dir>]
nestrs-cli db [--backend sqlx|prisma] migrate run [--path <dir>] [--target-version V] [--database-url URL]
nestrs-cli db [--backend sqlx|prisma] migrate revert [--path <dir>] [--target-version V] [--database-url URL]
nestrs-cli db [--backend sqlx|prisma] migrate info [--path <dir>] [--database-url URL]
nestrs-cli db [--backend sqlx|prisma] seed --bin <name> [--manifest-path <path>] [--database-url URL]
nestrs-cli db [--backend sqlx|prisma] seed --seed-file <path> [--database-url URL]

Global flags

Flag	Default	Description
`--backend sqlx \| prisma`	`sqlx`	Backend selector. `prisma` shells out to `npx prisma …` — the file naming and migration recording belong to Prisma.
`--path <dir>`	`./migrations`	Migration directory.
`--database-url URL`	—	Database URL. Resolution order: `--database-url` > `DATABASE_URL` > `NESTRS_DB__URL`.
`--target-version V`	latest / `0`	Stop migrating (or reverting) at version `V`.

migrate add

Writes empty SQL files you fill in. The naming convention is sequence-numbered — <NNN>_<name>.sql for single-shot, or <NNN>_<name>.up.sql + <NNN>_<name>.down.sql with --reversible. NNN is a zero-padded 3-digit sequence derived from the largest existing migration, incremented by one (deterministic, greppable, sortable — collisions surface immediately at add-time).

nestrs-cli db migrate add create_posts_table --reversible
# migrations/001_create_posts_table.up.sql
# migrations/001_create_posts_table.down.sql

migrate run / revert / info

run applies pending migrations up; revert walks down (set --target-version 0 for a full revert). info lists applied and pending migrations. The sqlx backend uses sqlx::migrate::Migrator under the hood, so _sqlx_migrations is the recording table.

nestrs-cli db migrate run
nestrs-cli db migrate revert --target-version 2
nestrs-cli db migrate info

The prisma backend has no revert — Prisma records its own migration history and does not support down-migrations. Use the sqlx backend (with —reversible) if you need downgrades.

seed

Two modes:

--bin <name> — pass-through to cargo run --bin <name> in the current directory. The resolved URL is forwarded to the seed binary as both DATABASE_URL and NESTRS_DB__URL. You own the seed binary; the common case is a Rust bin that composes with CrudService<T> and your app’s services.
--seed-file <path> — execute a SQL file against the resolved URL via sqlx::raw_sql inside an explicit transaction, so a failed INSERT mid-file rolls back earlier rows. The escape hatch for pg_dump-style fixture dumps.

nestrs-cli db seed --bin seed_posts
nestrs-cli db seed --seed-file fixtures/dev.sql

See the database ecosystem page for how the CLI composes with SqlxDatabaseModule, and the CRUD guide for #[crud] controllers over the same pool.

nestrs-cli new

nestrs-cli new <name> creates a ready-to-run single-crate application. Run it from any directory — it creates a new subdirectory named after your project.

nestrs-cli new billing-api
cd billing-api
cargo run

Flags

Flag	Default	Description
`--no-git`	off	Skip `git init` after creating the project.
`--strict`	off	Prepend `#![deny(unsafe_code)]` to `src/main.rs`.
`--package-manager cargo`	`cargo`	Only `cargo` is supported. Other values are rejected.

Use --dry-run on generators before writing to an existing tree — but nestrs-cli new always creates a fresh directory, so there is no equivalent flag for it.

Generated project structure

After nestrs-cli new billing-api, your project contains:

billing-api/
├── Cargo.toml
├── Dockerfile
├── README.md
├── .env
├── .env.example
├── .gitignore
└── src/
    └── main.rs

Cargo.toml

[package]
name = "billing-api"
version = "0.1.0"
edition = "2021"

[dependencies]
nestrs = "0.1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
serde = { version = "1", features = ["derive"] }

[profile.release]
opt-level = 3
lto = "thin"
codegen-units = 1
strip = "symbols"
panic = "abort"

src/main.rs

The generated entry point wires up a AppModule with a single controller and service, a health check endpoint, metrics, and request tracing. The --strict flag adds #![deny(unsafe_code)] at the top.

use nestrs::prelude::*;

#[dto]
pub struct PingDto {
    #[IsString]
    pub message: String,
}

#[controller(prefix = "/")]
pub struct AppController;

impl AppController {
    #[get("/")]
    pub async fn root() -> &'static str {
        "Hello from nestrs"
    }
}

#[derive(Default)]
#[injectable]
pub struct AppService;

impl_routes!(AppController, state AppService => [
    GET "/" with () => AppController::root,
]);

#[module(
    controllers = [AppController],
    providers = [AppService],
)]
pub struct AppModule;

#[tokio::main]
async fn main() {
    let port = std::env::var("PORT")
        .ok()
        .and_then(|v| v.parse::<u16>().ok())
        .unwrap_or(3000);

    NestFactory::create::<AppModule>()
        .set_global_prefix("api")
        .use_request_id()
        .use_request_tracing(RequestTracingOptions::builder().skip_paths(["/metrics"]))
        .enable_metrics("/metrics")
        .enable_health_check("/health")
        // OpenAPI + Swagger UI (add `features = ["openapi"]` on `nestrs` in Cargo.toml):
        // .enable_openapi()
        .enable_production_errors_from_env()
        .listen_graceful(port)
        .await;
}

.env and .env.example

Both files are created with identical default content:

PORT=3000
NESTRS_ENV=development
RUST_LOG=info
DATABASE_URL=file:./dev.db

.env is listed in .gitignore so it stays local. Commit .env.example to source control.

Dockerfile

A two-stage Docker build targeting debian:bookworm-slim. The binary name matches your project name.

FROM rust:1.75 AS builder
WORKDIR /app
COPY Cargo.toml Cargo.lock* ./
COPY src ./src
RUN cargo build --release

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates curl && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/target/release/billing-api /usr/local/bin/billing-api
ENV NESTRS_ENV=production
ENV PORT=3000
EXPOSE 3000
HEALTHCHECK CMD curl -f http://localhost:3000/health || exit 1
CMD ["/usr/local/bin/billing-api"]

README.md

A starter README with development, production, and Docker instructions. The app, health, and metrics URLs are pre-filled based on the generated main.rs defaults:

App: http://127.0.0.1:3000/api
Health: http://127.0.0.1:3000/health
Metrics: http://127.0.0.1:3000/metrics

nestrs-cli doctor

nestrs-cli doctor is a lightweight sanity check you run from the root of a nestrs crate (where Cargo.toml lives). It does not replace cargo check or your CI matrix — use it as a first-pass hint list.

nestrs-cli doctor

What it checks

Toolchain versions

Runs rustc --version and cargo --version and prints the results.

Cargo.toml feature flags

Reads the local Cargo.toml and reports which nestrs feature flags it detects: openapi, otel, ws, graphql, and microservices. It also queries cargo metadata to count the total resolved feature flags on the nestrs package.

Source file heuristics

Recursively scans src/**/*.rs and flags common mismatches, such as:

Calling enable_openapi() without the openapi feature enabled in Cargo.toml
Referencing configure_tracing_opentelemetry without the otel feature
Calling enable_graphql without the graphql feature
Using nestrs_openapi:: paths without the feature enabled

Example output when no issues are found:

nestrs-cli doctor

rustc: rustc 1.78.0 (9b00956e5 2024-04-29)
cargo: cargo 1.78.0 (54d8815d0 2024-04-09)

Cargo.toml (nestrs-related hints):
  - `nestrs` dependency found.
    Features detected (string heuristic): openapi=false, otel=false, ws=false, graphql=false, microservices=false

Source scan (heuristic):
  - No obvious feature mismatches from quick scan.

Done. This does not replace `cargo check` or security audits.

nestrs-cli doctor uses string heuristics on your source files — it can produce false positives and will miss issues that only appear at compile time. Always follow up with cargo check and your full CI pipeline.

Scope compared to the Nest CLI

The Nest CLI covers application lifecycle management, monorepos, publishable library packages, and npm-style scripts. nestrs intentionally stays closer to Cargo and normal Rust workflows.

The nestrs CLI focuses on file and code generation and a single-crate nestrs-cli new skeleton. It does not replace Cargo for workspaces, libraries, or task runners.

Nest CLI area	nestrs	What to use instead
`nest new` / app skeleton	Partial	`nestrs-cli new` — single crate, opinionated starter.
`nest generate`	Partial	`nestrs-cli generate` — overlapping generators; naming and file trees differ.
Workspaces (multiple apps/libs)	No	Cargo workspaces with `[workspace].members`.
Publishable library packages	No	`cargo new --lib`, crates.io, path/git dependencies.
Scripts (`npm run …`)	No	`cargo run --bin <name>`, cargo-make, just, or shell scripts.
`nest build` / `nest start`	No	`cargo build`, `cargo run`; production: binary + process manager or container.
CLI plugins	No	Fork or wrap `nestrs-scaffold`, or generate with your own templates.

Get Started

Core Concepts

Guides

Ecosystem

Adapters

CLI

Migration

nestrs CLI: scaffold and manage projects

Install

Available commands

nestrs-cli db

Global flags

migrate add

migrate run / revert / info

seed

nestrs-cli new

Flags

Generated project structure

nestrs-cli doctor

What it checks

Scope compared to the Nest CLI

​Install

​Available commands

​nestrs-cli db

​Global flags

​migrate add

​migrate run / revert / info

​seed

​nestrs-cli new

​Flags

​Generated project structure

​nestrs-cli doctor

​What it checks

​Scope compared to the Nest CLI

Install

Available commands

nestrs-cli db

Global flags

migrate add

migrate run / revert / info

seed

nestrs-cli new

Flags

Generated project structure

nestrs-cli doctor

What it checks

Scope compared to the Nest CLI