Skip to content

CLI

Install the nestrs binary, scaffold a workspace or an app, run its tasks and build it — and where each other command is.

The nestrs CLI scaffolds one layout: a workspace — crates/features/ for your domain, apps/* for the binaries that serve it. nestrs new reads the directory tree to know whether it is creating that workspace or adding an app to one you already have; there are no mode flags and no config file. Generated code follows the same decorators as the framework repo (users/ for features, api/ for composition apps).

Terminal window
cargo install --locked nest-rs-cli
nestrs version

A binary, so it is the one thing that does not come through the nest-rs umbrella — there is no --features cli.

Requires Rust 1.100+ (edition 2024). That single install is all you need: the first time you call nestrs run, the CLI installs the dev toolchain it drives — just, bacon, cargo-nextest, cargo-llvm-cov — once. Run nestrs doctor after install to check the Rust toolchain and list optional <PREFIX>_* environment variables.

nestrs new infers where you are and what to create. There is no nestrs-cli.yaml — the workspace shape is already declared in the root Cargo.toml (members = ["crates/*", "apps/*"]). The CLI walks up from the current directory (or -o path) and reads that manifest.

Where you runCommandResult
Outside a nestrs workspacenestrs new helloMonorepo at ./hello/ + apps/hello/ on port 3000
Inside a nestrs workspacenestrs new blogThin app at apps/blog/ — next free port in apps/blog/.env

If apps/blog/ already exists, the CLI stops with app `blog` already exists at <path>: it does not overwrite.

Terminal window
nestrs new hello
cd hello
nestrs run dev hello

Open http://localhost:3000/ — Hello World. Logic in crates/features/src/hello/; apps/hello/ composes modules only.

  • Directoryhello/
    • Cargo.toml
    • Justfile
    • test.just
    • db.just
    • compose.yml
    • .env
    • .env.development
    • .env.test
    • .env.example
    • .gitignore
    • rust-toolchain.toml
    • clippy.toml
    • README.md
    • AGENTS.md the conventions every coding agent reads
    • CLAUDE.md imports AGENTS.md
    • Directorycrates/
      • Directoryfeatures/
        • Cargo.toml
        • Directorysrc/
          • Directoryhello/
            • http/…
            • service.rs
          • lib.rs
      • Directorymigrations/ SeaORM migrations + the migrate binary
        • …
      • Directoryseed/ the seed binary
        • …
    • Directoryapps/
      • Directoryhello/
        • .env the port
        • Directorysrc/
          • lib.rs
          • main.rs
          • module.rs
        • Directorytests/
          • integration/main.rs
          • e2e/main.rs

The e2e suite is scaffolded empty. It has to exist: nestrs run test integration filters on not binary(e2e) and nestrs run test e2e on binary(e2e), and nextest rejects a filterset naming a binary the workspace does not have.

Grow the workspace (from the workspace root or any sub-folder):

Terminal window
nestrs new blog
nestrs g resource posts title:string body:text --app blog

rust-toolchain.toml is what makes every recipe run on a project minutes old. It pins Rust 1.100 as the toolchain channel, plus three components, each because a recipe shells out to it:

  • clippy and rustfmt are what nestrs run lint runs. Undeclared, they are present only because rustup’s default profile happens to install them — so the recipe works on your machine and fails on a minimal one.
  • llvm-tools-preview carries the llvm-cov and llvm-profdata behind nestrs run test cov. Those two read a .profraw only when they come from the same LLVM as the rustc that wrote it, so they are pinned here, beside channel, rather than installed once per machine: following the channel is what keeps the two versions married.

Rustup is what reads that file. On a toolchain installed any other way it is inert — point LLVM_COV and LLVM_PROFDATA at your own binaries instead.

clippy.toml names raw SQL (Expr::cust and every other call writing text unescaped) in nestrs run lint, where it is written: no type tells it from a condition, and Repo refuses a fragment that would read past the ability’s filter only when the query runs (Raw SQL in a filter). crates/migrations holds an empty one of its own, which lets a migration write raw DDL.

There is nothing to choose. Every path out of nestrs new writes the same hello module — a service with a greeting and one #[public] GET / that returns it:

What you runWhat you getGET /
nestrs new acmemonorepo + hello feature + apps/hello/ on 3000200 Hello World
nestrs new blog (inside one)blog feature + apps/blog/ on the next free port200 Hello World

A freshly created project has to prove it started, and a 404 proves nothing to someone looking at a browser — so there is no routeless variant to pick. Delete the feature once you have a real one; nestrs new blog refuses if a blog feature already exists, rather than overwriting it.

Ports: the CLI reads the port each existing app listens on — from its .env, a port pinned in its root, or the default when its root names a module or host serving HTTP — and writes the next free one into the new app’s own .env (same pattern as auth → 3001, api → 3002, …). A root reaching its host through a module whose name says no edge counts as not listening, so two apps can land on one port; the second to start fails its boot at the listen, naming the address. The workspace’s root .env files do not set <PREFIX>_HTTP__PORT, and no module.rs pins it — a pin would take the app’s whole HTTP namespace off the .env cascade:

apps/api/.env
NESTRS_HTTP__PORT=3002
NESTRS_AUTHN__ISSUER=http://localhost:3002
NESTRS_AUTHN__AUDIENCE=http://localhost:3002

Beside the port, the app’s origin is the issuer and the audience of the tokens it mints and verifies once it authenticates — JwtService does not start without them (JWT) — and the lines sit unread until then. An app’s own files are read over the root’s under the development and test profiles (an app’s own files); a deployment sets all three on the process.

Optional: --check runs cargo check after generation.

From the workspace root (or apps/, crates/features/, …):

Terminal window
nestrs new blog
nestrs run dev blog

Creates a thin app under apps/blog/ — composition root only, no service.rs / controller.rs in the app crate — plus the blog feature it serves under crates/features/src/blog/. That split is why the greeting is a feature rather than a controller in the app: the layout keeps no business logic in an app crate, so the same rule that governs your code governs the starter.

Every project task runs through nestrs run <recipe> — the single front door. It forwards the recipe and its arguments verbatim to just, which reads the Justfile the scaffolder wrote:

Terminal window
nestrs run dev # watch mode (rebuild + restart on save)
nestrs run test integration # in process, no database
nestrs run db up # apply migrations
nestrs run # list the available recipes

The recipes are yours to edit. Add your own to the Justfile and they run the same way — nestrs run deploy, nestrs run docker-up, whatever you write. The framework owns the recipes it ships; you own the rest.

The first nestrs run installs the toolchain it drives (just, bacon, cargo-nextest, cargo-llvm-cov) once — all of it, whichever recipe you asked for, so no recipe is ever a step behind. On CI, where you provision tools yourself, set NESTRS_NO_BOOTSTRAP=1 or pass --no-bootstrap — a missing tool then fails with the manual install command instead of fetching anything.

Release binaries land in target/release/. nestrs run start compiles and starts the server under the production profile, so it reads no .env.development: the database and queue URLs are the deployment’s to set. Use nestrs run build when you only need the artifact (Docker, CI, or copying the binary elsewhere).

Terminal window
nestrs run build # default app (hello)
nestrs run build blog # after nestrs new blog
nestrs run build --all # every app in the workspace
nestrs run start hello # build + run in release
CommandDescription
nestrs new <name>Monorepo at ./<name>/, or app at apps/<name>/ when already inside one
nestrs new <name> --checkRun cargo check after scaffolding
nestrs doctorToolchain and env sanity check
nestrs lintEvery file named for what it declares
nestrs versionPrint the CLI version
nestrs aboutPrint NestRS metadata (tagline, docs, license, author)
nestrs infoReport the project the current directory sits in
nestrs updateInstall latest CLI from crates.io when a newer version exists
nestrs update --forceReinstall from crates.io even when already on the latest version
nestrs g feature <name>Transport-agnostic port in crates/features/src/
nestrs g resource <name> [<column>:<type>[:nullable]…]DB-backed CRUD port + guarded HTTP adapter, its table’s migration and round trip (deps auto-added)
nestrs g entity <feature>[/<name>]One #[expose] entity in an existing feature
nestrs g authThe app’s authn/authz adapter — one per workspace
nestrs g migration <name>SeaORM migration, registered in lib.rs and migrator.rs, its columns an entity’s for create_<table>; nestrs_outbox registers the framework’s own
nestrs run [<recipe> [args…]]Run a project task through just; bare, list the recipes
nestrs g http|graphql|ws|queue|schedule|mcp|events <name>Add one transport adapter to a port

Every generator accepts --dry-run and -p <path>; the ones that wire an app (resource, auth and the adapters) also take --app <name>. Aliases: nestrs g = nestrs generate. All of them require a workspace, which is what nestrs new writes.

Each generator is told on Generators; doctor, lint, info and update on Doctor, lint and info.

  • Generators — what each nestrs g writes and wires, and why every generated unit is guarded.
  • Getting started — first run after nestrs new.
  • Tutorial — build posts in apps/blog/, over HTTP and then GraphQL.
  • Move an existing crate — bring a crate you already have under crates/features/.