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).
Install
Section titled “Install”cargo install --locked nest-rs-clinestrs versionA 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.
Layout detection
Section titled “Layout detection”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 run | Command | Result |
|---|---|---|
| Outside a nestrs workspace | nestrs new hello | Monorepo at ./hello/ + apps/hello/ on port 3000 |
| Inside a nestrs workspace | nestrs new blog | Thin 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.
Create a project
Section titled “Create a project”nestrs new hellocd hellonestrs run dev helloOpen 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
migratebinary- …
Directoryseed/ the
seedbinary- …
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):
nestrs new blognestrs g resource posts title:string body:text --app blogrust-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:
clippyandrustfmtare whatnestrs run lintruns. Undeclared, they are present only because rustup’s default profile happens to install them — so the recipe works on your machine and fails on aminimalone.llvm-tools-previewcarries thellvm-covandllvm-profdatabehindnestrs run test cov. Those two read a.profrawonly when they come from the same LLVM as the rustc that wrote it, so they are pinned here, besidechannel, 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.
One starter, no template flag
Section titled “One starter, no template flag”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 run | What you get | GET / |
|---|---|---|
nestrs new acme | monorepo + hello feature + apps/hello/ on 3000 | 200 Hello World |
nestrs new blog (inside one) | blog feature + apps/blog/ on the next free port | 200 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:
NESTRS_HTTP__PORT=3002NESTRS_AUTHN__ISSUER=http://localhost:3002NESTRS_AUTHN__AUDIENCE=http://localhost:3002Beside 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.
Add an app to an existing workspace
Section titled “Add an app to an existing workspace”From the workspace root (or apps/, crates/features/, …):
nestrs new blognestrs run dev blogCreates 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.
Running tasks
Section titled “Running tasks”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:
nestrs run dev # watch mode (rebuild + restart on save)nestrs run test integration # in process, no databasenestrs run db up # apply migrationsnestrs run # list the available recipesThe 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).
nestrs run build # default app (hello)nestrs run build blog # after nestrs new blognestrs run build --all # every app in the workspacenestrs run start hello # build + run in releaseCommand reference
Section titled “Command reference”| Command | Description |
|---|---|
nestrs new <name> | Monorepo at ./<name>/, or app at apps/<name>/ when already inside one |
nestrs new <name> --check | Run cargo check after scaffolding |
nestrs doctor | Toolchain and env sanity check |
nestrs lint | Every file named for what it declares |
nestrs version | Print the CLI version |
nestrs about | Print NestRS metadata (tagline, docs, license, author) |
nestrs info | Report the project the current directory sits in |
nestrs update | Install latest CLI from crates.io when a newer version exists |
nestrs update --force | Reinstall 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 auth | The 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.
Going further
Section titled “Going further”- Generators — what each
nestrs gwrites and wires, and why every generated unit is guarded. - Getting started — first run after
nestrs new. - Tutorial — build
postsinapps/blog/, over HTTP and then GraphQL. - Move an existing crate — bring a crate you already
have under
crates/features/.