CLI

The nestrs CLI scaffolds projects in two layouts — standalone (one crate) or workspace (monorepo with crates/features/ + apps/*). nestrs new picks the layout automatically from the directory tree — no mode flags, no config file. Generated code follows the same decorators as the framework repo (users/ for features, api/ for composition apps).

Caution

The CLI ships on crates.io as nest-rs-cli (binary name nestrs), lockstep with the other nest-rs-* crates.

Install

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

Requires Rust 1.95+ (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 — once. Run nestrs doctor after install to check the Rust toolchain and list optional NESTRS_* environment variables.

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 module.rs
Anywhere (explicit)	nestrs new hello --standalone	Single crate at ./hello/

If apps/blog/ already exists, the CLI stops with app blog already exists — it does not overwrite.

Note

No extra config file to maintain. Cargo’s workspace manifest is the single source of truth; the generators use the same discovery as nestrs new. If you ever need to tune defaults, an optional [workspace.metadata.nestrs] table in the root Cargo.toml accepts port-base — never required, every key has a default.

Standalone vs workspace

	Standalone (--standalone)	Workspace (default)
Layout	One crate — logic in src/	Monorepo — crates/features/ + apps/*
Deps	nest-rs-* from crates.io	Same, via [workspace.dependencies]
Grow	Copy patterns by hand	nestrs g feature / g resource / g <transport>, nestrs new <app>
When	One binary, no shared product crate	Several apps sharing features

Create a project

Workspace

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
  • README.md
  • Directorycrates/

    • Directoryfeatures/

      • Directorysrc/

        • Directoryhello/

          • http/…
          • service.rs
        • lib.rs
  • Directoryapps/

    • Directoryhello/

      • Directorysrc/

        • lib.rs
        • main.rs
        • module.rs
      • tests/e2e.rs

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

nestrs new blog
nestrs g resource posts

Standalone

nestrs new hello --standalone
cd hello
nestrs run dev

Open http://localhost:3000/ — Hello World. Service and controller live in src/ (no features crate).

• Directoryhello/

  • Cargo.toml
  • Dockerfile
  • Justfile
  • Directorysrc/

    • controller.rs
    • service.rs
    • module.rs
    • main.rs
  • tests/e2e.rs

Optional Dockerfile ships in standalone mode only. rust-toolchain.toml pins Rust 1.95 in both modes.

Templates — --template applies to new monorepos and standalone crates only. Every workspace app uses the same thin shell; the CLI scans existing apps/*/src/module.rs files and pins the next HTTP port in code (same pattern as auth → 3001, api → 3002, …).

What	Default	Override
New monorepo	hello — feature + apps/hello/ on port 3000	--template empty
New workspace app	thin shell + auto port in HttpConfig	(no template flag)
Standalone crate	hello	--template empty

Workspace .env files do not set NESTRS_HTTP__PORT — ports live in each app’s module.rs:

HttpModule::for_root(HttpConfig { port: 3002, ..Default::default() })

Optional: --check runs cargo check after generation.

Add an app to an existing workspace

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

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).

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 unit         # unit + integration
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) once. 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.

Build

Release binaries land in target/release/. nestrs run start compiles and starts the server; use nestrs run build when you only need the artifact (Docker, CI, or copying the binary elsewhere).

Workspace

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

Standalone

nestrs run build    # target/release/hello
nestrs run start    # build + run in release

The standalone Dockerfile runs cargo build --release in a multi-stage image — same output path as nestrs run build.

Generate features and adapters

Monorepo only. Generators scaffold under crates/features/src/<name>/, register pub mod … in crates/features/src/lib.rs, and — when you run them from inside an app — wire the edge module into that app’s module.rs. Every command takes --dry-run (print what would change, write nothing) and a -p path override (default: auto-discover from the current directory). Re-running a generator is safe: it refuses to overwrite an existing feature or adapter, and the wiring edits are idempotent.

A port is the transport-agnostic core (service + module). An adapter bolts one transport onto a port. A resource is a DB-backed CRUD port plus its HTTP adapter in one shot.

# Port only (service + module, no transport)
nestrs g feature posts

# DB-backed CRUD: #[expose] entity + CrudService + HTTP adapter, deps auto-added
nestrs g resource posts

# Bolt a transport onto an existing port
nestrs g http posts        # controller
nestrs g graphql posts     # resolver
nestrs g ws posts          # gateway
nestrs g queue posts       # processor
nestrs g schedule posts    # scheduled tasks
nestrs g mcp posts         # MCP tool

Note

Generated entities default to wire-only #[expose] (no GraphQL tokens). Add the graphql flag and features = ["graphql"] on nest-rs-resource when you bolt on GraphQL — see HTTP-only resources.

Each adapter delegates to the port’s service, so a freshly-generated port plus any adapter compiles immediately — the handler is the seam you fill in. The generator prints the import line and the app-level module each transport needs (HttpModule, GraphqlModule, ScheduleModule, …).

When the cursor isn’t inside an app, wire the edge module by hand:

use features::posts::PostsHttpModule;

#[module(imports = [
    // …
    PostsHttpModule,
])]
pub struct ApiModule;

g resource emits a self-contained, unauthenticated slice so it compiles in any workspace. For auth-protected CRUD, copy the #[crud] + guard wiring from orgs/ or users/ and import the matching Authz<Transport>Module.

Tip

Before inventing a second layout, open crates/features/src/users/ side by side with what the generator emitted.

Doctor

nestrs doctor

Checks:

• rustc ≥ 1.95 and cargo on PATH
• whether the current directory sits inside a nestrs workspace
• optional env vars (NESTRS_DATABASE__URL, NESTRS_QUEUE__URL, …)

Use it after install and before running DB- or Redis-backed apps.

Version, about, and update

nestrs version
# → NestRS 0.1.0

nestrs about
# → version, tagline, docs, repository, license, author

nestrs update
# → checks crates.io; skips when already on the latest version

nestrs update --force
# → cargo install --force nest-rs-cli (reinstall even at the same version)

Contributors inside the monorepo clone:

nestrs update --from-path
# → cargo install --locked --path crates/nest-rs-cli --force

Command reference

Command	Description
nestrs new <name>	Monorepo at ./<name>/, or app at apps/<name>/ when already inside one
nestrs new <name> --standalone	Single crate in ./<name>/
nestrs new <name> --template hello	Force Hello World scaffold
nestrs new <name> --template empty	Force HTTP-only shell (no routes)
nestrs new <name> --check	Run cargo check after scaffolding
nestrs doctor	Toolchain and env sanity check
nestrs version	Print the CLI version
nestrs about	Print project metadata
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 update --from-path	Reinstall from monorepo crates/nest-rs-cli
nestrs g feature <name>	Transport-agnostic port in crates/features/src/
nestrs g resource <name>	DB-backed CRUD port + HTTP adapter (deps auto-added)
nestrs g http|graphql|ws|queue|schedule|mcp <name>	Add one transport adapter to a port

Every generator accepts --dry-run and -p <path>. Aliases: nestrs g = nestrs generate.

What’s next

Planned generators (see Roadmap): migration scaffold and nestrs info (route/module scan).

• Getting started — first run after nestrs new
• Tutorial — build posts in apps/blog/ (HTTP only)
• Fundamentals / Modules — how root modules compose features