zudojs-cli

NEW IN 2.1

2.1 is about what the CLI writes. A project fresh out of create now runs, answers real requests and passes its tests, and every generate and add writes code that is already wired in and compiles. Nothing you typed against 2.0 stops working.

• Two install names, two command names. npm install -g zudojs works as well as zudojs-cli, and both give you zudojs and the short alias zudo. See Installation.
• new is an alias of create, and running zudo with no arguments in a terminal opens a numbered menu.
• Wired projects. src/server.ts builds a router, applies security headers, closed-by-default CORS and rate limiting, and serves an example /api/v1/examples resource, /health, /openapi.json and /docs. See What a new project contains.
• generate resource <name> writes a complete CRUD endpoint (DTO, repository, service, controller, routes, test) and registers it. See generate resource.
• add writes real integrations for database (Prisma 7), redis, websockets, email, docker and seven more, instead of only installing a package. See Add.
• Clear exit codes. Usage errors exit 2, unknown commands exit 3 with a “Did you mean” hint. See Exit codes.
• A stricter parser. Only the first word selects the command, so a typo no longer runs a different command and exits 0. Extra words after -v, an empty --port=, a non-finite number such as Infinity, and --__proto__-style option names are all usage errors, and control characters in anything the CLI echoes back are escaped.
• Current toolchains. Backends get TypeScript 7, Vitest 5 and @types/node 26; frontend templates were moved to Vite 8, React 19.3, Next 16, Nuxt 4, Astro 7, Angular 22 and SvelteKit 2.70. See Frontend and fullstack.

UPGRADING TO 2.0

What to change in a CI job

• A job that ran zudojs create and relied on exit 0 to mean “scaffolded” now also gets “and installed”. If you do not want the install, pass --no-install rather than ignoring the failure.
• A job that ran zudojs build from a directory that is not inside a Zudojs project was building something else. Run it from the project, or from any directory inside it.
• Pin the capability set explicitly with --capabilities instead of relying on the non-interactive default, which is now also reachable from the interactive prompt.

OVERVIEW

zudojs-cli is the command-line interface for the Zudo framework. It provides project scaffolding, code generation, dependency management, and project diagnostics — all with interactive prompts powered by @clack/prompts.

The CLI supports 11 frontend frameworks (React, Next, Vue, Nuxt, Angular, Svelte, SvelteKit, Astro, Vanilla, Flutter, React Native), 4 package managers (pnpm, npm, yarn, bun), 3 database engines (PostgreSQL, MySQL, SQLite), 14 code schematics (from a whole CRUD resource down to a single validator) and 12 features for add, from a Prisma database to a Dockerfile.

Upgrading from 1.2.x? Read Upgrading to 2.0 first — several commands now refuse where they used to proceed.

INSTALLATION

The CLI is a program you run in a terminal. It writes new projects and new files for you, so you do not have to set up folders, wiring and configuration by hand. You need Node.js 24 or newer.

Both packages install the same CLI under two command names: zudojs and the short alias zudo. Use whichever you like; this page mostly writes zudo. The zudojs package is a thin wrapper that runs zudojs-cli, so the two can never disagree about behaviour or version.

Help text, usage lines and error messages repeat the name you typed. Type zudo and the hints say zudo:

Binaries: zudojs-cli installs zudojs, zudo and zudojs-cli, all pointing at ./dist/src/bin/zudojs.js. The zudojs package (currently 1.0.1, which depends on zudojs-cli 2.1.0) installs zudojs and zudo, and its bin/zudojs.js only imports zudojs-cli/bin.

INTERACTIVE MENU

If you do not remember a command, run zudo (or zudojs) on its own. In a terminal it opens a numbered menu:

Press a digit to pick an entry at once, or move with the arrow keys and press Enter. Each entry runs the ordinary command and asks for whatever it needs: “Create” runs the usual create questions, “Generate code” asks for the schematic and the name, “Add a feature” asks which feature. “Start dev server”, “Generate code”, “Add a feature” and “Build” need a Zudojs project; outside one the menu says so and shows itself again.

0 exits with status 0. Esc or Ctrl+C prints “Operation cancelled.” and exits with 130, like every other prompt.

EXIT CODES

Every program ends with a number called its exit code. 0 means it worked; anything else means it did not. Scripts and CI jobs read this number to decide whether to continue, so the CLI keeps it precise:

Options go after the command name (zudo dev --port 4000). An option placed before it is reported rather than silently dropped, and only the first word can be the command, so a typo is an error instead of a different command:

zudojs build and zudojs doctor exit non-zero when they fail, so both work as CI gates.

QUICK START

The whole loop in eight commands. Your First App walks through the same steps slowly, with the output of each one.

The same create without any questions, for scripts and CI. The project name is a positional argument, not --project-name:

BUILT-IN COMMANDS

The CLI ships with 7 built-in commands. create prompts interactively in a terminal and takes flags otherwise; the rest read the project from .zudojs/manifest.json (or the zudojs block in package.json) and refuse to run outside a Zudojs project. You can run them from any folder inside the project: the CLI walks up to find its root.

Every command documents itself: zudo <command> --help, -h and zudo help <command> all print the same block. Before 2.0 the first two were handed to the parser, which rejected --help as an undeclared option and exited 2, so no command’s flags could be discovered from the CLI itself.

One command’s help, in full:

CREATE

Scaffold a new Zudo project with interactive prompts or explicit flags. Supports backend, frontend, and fullstack project types.

Interactive Mode

The services prompt appears only for a microservice architecture, and the database, API-style and frontend prompts only for the project types that have them. Flags you pass on the command line seed the matching prompt, so zudojs create my-app --architecture microservice --capabilities cqrs,security opens with those already selected.

Cancelling any prompt with Ctrl-C ends the run with status 130; answering “no” at the confirmation ends it with 0 and writes nothing. Ctrl-C after the scaffold has started removes the partially written directory before exiting.

Non-Interactive Mode

A run is non-interactive whenever stdin is not a TTY. Without --capabilities such a run enables the set it has always hard-coded — cqrs, messaging, observability, openapi and database — so adding the flag in 2.0 does not change what an existing command line produces.

Argument

Options

Capabilities

--capabilities is honoured by both branches: it seeds the interactive multiselect and it replaces the hard-coded set in a non-interactive run, so the two ways of running create can produce the same project. Selected capabilities are recorded as capabilities in .zudojs/manifest.json and as zudojs.features in each backend package.json, and the packages that back them are added as dependencies.

Before 2.0 the prompt offered eight options and the command read six: ticking Events or Security produced no dependency, no manifest entry and no message. Both are consumed now — ticking Security installs @zudojs/security.

No example services

An empty service list now means no services. A microservice project gets its gateway at apps/gateway and nothing under apps/services/; a modular monolith gets an empty module barrel at src/modules/index.ts. Both READMEs say how to add one. Named services are generated exactly as named, at apps/services/<name>. Every backend app does get one example HTTP resource, /api/v1/examples, to show how the layers connect; delete it once you have your own.

Before 2.0 the templates substituted example domains nobody asked for — identity, enrollment, assessment and notification for a microservice project, and three modules for a modular monolith, which was never even asked what it wanted.

What a new project contains

A backend project is ready to run the moment create finishes. Here is what zudo create my-api -p pnpm --no-git --no-install prints:

• A wired HTTP server. A request travels src/server.ts → router → registerRoutes (src/routes/index.ts) → controller → service → repository. src/container.ts is the one place every controller, service and repository is built; src/app.ts assembles the runtime; src/configs/index.ts reads typed settings from .env. The Project Structure page walks through each file.
• Routes that answer. An example CRUD resource at /api/v1/examples, GET /health (200 when the runtime and every integration are up, 503 otherwise), and, with the openapi capability (on by default), the OpenAPI document at /openapi.json and a docs page at /docs.
• Safe defaults. Every response gets the @zudojs/security headers (CSP, HSTS, nosniff, X-Frame-Options: DENY, …). CORS is closed until you list origins in CORS_ORIGINS, and each client is rate limited by RATE_LIMIT_MAX requests per RATE_LIMIT_WINDOW_MS (300 per 60 000 ms by default).
• A place for integrations. src/integrations/ holds clients with a lifecycle (Redis, the database, WebSockets, email). They start before the rest of the app and stop after it; on SIGINT/SIGTERM the server drains integrations, then stops HTTP, then the runtime.
• A test that passes. tests/examples.test.ts drives the example routes through createHttpTestClient from @zudojs/testing, so pnpm test is green on a fresh project.
• Markers the CLI writes between. Lists the CLI appends to are fenced by comments such as // zudojs:routes:start and // zudojs:routes:end. generate and add only insert between them. Do not delete them: a file without its markers is left alone, and you are told what to add by hand.
• No zudojs.config.ts. The project’s type, architecture, package manager and capabilities live in the zudojs block of package.json and in .zudojs/manifest.json (machine-managed). Every follow-up command reads them from there.
• Real recorded capabilities. Templates write the capability list into zudojs.features and install the packages backing it, so the zudojs doctor feature check has something to verify.
• Framework versions that match the CLI. @zudojs/* packages are added as caret ranges of the versions this CLI build targets (for example "@zudojs/http": "^1.4.0"), so a new project never resolves an older release that lacks an API the templates use. Projects created for pnpm also get a pnpm-workspace.yaml that allows esbuild’s build script, which pnpm 10+ would otherwise refuse to run.
• Pinned frontend dependencies. The frontend install path passes the resolved name@range to the package manager instead of the bare name, so two create --frontend react runs a month apart do not produce different majors.

Frontend and fullstack

--type frontend creates only a web or mobile app; --type fullstack creates a workspace with the backend at apps/api, the frontend at apps/web, and shared packages/contracts and packages/shared-types. The root package.json runs dev, build, test, lint and typecheck across every app. In a fullstack microservice project the gateway and services sit at apps/gateway and apps/services/<name>, next to apps/web.

For each framework the CLI first runs its official starter (create-vite, create-next-app, nuxi init, the Angular CLI, create-astro, npm create svelte, …). When that is not available it writes a built-in template instead, pinned to these current majors:

GENERATE

generate (alias g) writes new source files into an existing project, following the project’s layout, and registers them where they need to be registered. A schematic is the kind of thing to generate: resource, module, command, and so on. There are 14.

It reads .zudojs/manifest.json (or the zudojs block in package.json) to find the architecture and where the backend lives: src/ of a backend project, apps/api/src/ of a monolithic fullstack workspace, and apps/gateway or apps/services/<name> in a microservice project.

generate resource

A resource is one kind of thing your API manages, such as users or books, with the five standard operations: list, get one, create, update and delete (“CRUD”). generate resource writes every layer for it and wires them in, so the endpoint works as soon as the server restarts:

--module <name> puts the layers inside a module (src/modules/catalog/dtos/products.dto.ts, …) and registers the routes in that module’s routes/index.ts. In a microservice project, --service <name> puts them in that service’s app (apps/services/billing/src/…); without it they go to apps/gateway.

Once the app has a database, a dry run shows the Prisma files and the step left to you:

What each schematic writes

Paths are for a monolith. route, controller, repository and dto write their own layer plus any lower layer that is missing, so the result always compiles.

Missing dependencies are added for you

If a generated file imports a @zudojs/* package the app does not depend on yet, generate adds it to the owning package.json (at the version this CLI targets) and tells you to install, instead of leaving a Cannot find module error behind. In a project created without the cqrs capability:

Names

Type the name however you like; files use lower-case words joined by hyphens and classes use PascalCase. camelCase keeps its word boundaries, so createBook becomes create-book and CreateBookCommand:

A name is a name, not a path: anything containing /, \ or .. is refused, so a generator can never write outside its folder. A name that would start with a digit is refused too, because it becomes a TypeScript class name. Both exit 1 and write nothing:

--service and --module values must also be a single safe path segment.

Running it twice, --force and --dry-run

generate never overwrites a file that already exists and would change. Running the same name twice fails cleanly, lists the files and exits 1:

--force rewrites those files (your edits in them are lost). Registrations between markers are only ever added, never duplicated. --dry-run prints the file list and writes nothing.

Options

Available Schematics

Architecture-Aware Placement

Every other schematic follows the same root: src/ in a monolith or modular monolith, and apps/gateway/src — or apps/services/<name>/src with --service <name> — in a microservice project. Adding --module <name> nests the result in <root>/modules/<name>.

generate service, per architecture

generate service was broken in all three architectures before 2.0. What it does now:

• monolith — writes to src/services/<name>/, under the directory the template already owns. It used to write src/<name>/, leaving two conventions in one project and a service that the src/services/index.ts barrel never exported.
• modular monolith — the schematic is rewritten to module, generated at src/modules/<name>/ and registered in app.ts. It used to log Mapping "service" → "module" and then run the service schematic anyway, producing four inert files the runtime never loaded.
• microservice — refused. A service there is a whole workspace app (package.json, tsconfig.json, Dockerfile, src/app.ts, src/server.ts and a port), which this schematic does not produce. It used to write a bare service class into apps/services/<name>/; that directory matches the workspace glob but has no manifest, so pnpm skipped it, pnpm -r run build never compiled it, and zudojs add --service <name> reported it as unknown — all while exiting 0. The error names the two commands that do work:

generate module

zudo generate module <name> writes a runtime module (a BaseModule subclass that the runtime starts and stops), a features/ folder and a routes/index.ts for the module’s own endpoints. It exports the module from the modules barrel, registers it in app.ts, and registers its routes in src/routes/index.ts. If it cannot edit one of those files automatically it says so and prints the lines to add by hand.

ADD

add plugs a feature into an existing project: a database, a Redis connection, a WebSocket server, email, Docker files, and more. It does not just install a package. It writes working code, registers it, adds its settings to src/configs/index.ts and its variables to .env.example, adds the dependencies, records the feature in package.json and the manifest, and installs (skip that with --skip-install).

Most features become an integration: a file in src/integrations/ that starts with the app, stops after it, and reports its health on /health. Files that already exist are kept, so running add twice is safe.

The examples below pass --skip-install so the output fits on the page. Without it, add prints Installing dependencies with pnpm... (or your package manager) and the installer’s own output just before the “added successfully” line.

Available features

Aliases

postgres, postgresql and prisma mean database; ws and websocket mean websockets; mail means email. A second run keeps what is there:

The database recipe supports PostgreSQL only, because @zudojs/database is a PostgreSQL layer. A project created with --database mysql or sqlite is told so and nothing is written.

Refused: docs and security

Two names people try are refused with an explanation, exit 1, and change nothing:

Docker

zudo add docker packages the app as a container image. The Dockerfile is multi-stage (build with dev dependencies, ship only production ones) on Node 24, runs as the unprivileged node user rather than root, and has a HEALTHCHECK that calls /health. In compose.yaml the app is published on its port, while databases and other backing services bind to 127.0.0.1 only, so they are not reachable from other machines. With the database feature on, docker compose refuses to start until you set POSTGRES_PASSWORD in .env, so no database runs with a default password.

A project that already has a compose file (microservice projects are created with docker-compose.yml) keeps it.

Microservice projects

Without --service, add applies the feature to every backend app. --service <name> (or --service gateway) applies it to one. The root package.json is updated too, because it records the project’s features:

Since 2.0 the manifest is read and validated before any package.json is touched, so a failure can no longer leave the project half-updated. It is written atomically and serialized by a lock, so two concurrent zudojs add runs cannot lose an update, and a corrupt manifest is reported distinctly from a missing one.

DOCTOR

Run project diagnostics to check for common issues. Each check is either an error or a warning; doctor exits non-zero when any error-severity check fails, so it can be used as a CI gate. Warnings are printed and do not change the exit code.

The Features check could never report anything before 2.0: every template stamped zudojs.features: [] into the package.json it wrote, although it had already used the capability flags to choose the project’s dependencies, so the check passed vacuously in every project the CLI created. Templates now record the real capability list and install the packages backing it, so the check has something to verify.

Checks Performed

INFO

Display the CLI version, the project’s recorded type, architecture, package manager and capabilities, and the Zudo dependencies of each backend app. Also asks npm whether a newer zudojs-cli exists (set ZUDOJS_NO_UPDATE_CHECK=1 or CI to skip that).

ADAPTERS

The CLI uses adapter patterns for frontend frameworks, package managers, and databases.

Frontend Adapters (11)

Package Manager Adapters (4)

Database Adapters (3)

GENERATORS

Code generators for different project aspects.

APPLICATION API

Create custom CLI applications using the ZudojsCLI class.

ZudojsCLI Methods

PARSER

Parses CLI arguments into structured commands, options, and positional arguments.

Helper Functions

TYPES REFERENCE

ProjectConfiguration

ScaffoldOptions

CLICommand

CLIContext

RollbackResult

Changed in 2.0. RollbackManager.rollback() returned Promise<void> and swallowed whatever it could not remove. It now reports both halves, so a caller can tell the user what was left behind.

CapabilityResolutionResult

Changed in 2.0. The conflicts field is gone — it was structurally incapable of being non-empty.

CONSTANTS

CLI_ENVIRONMENT

The environment variables the CLI reads. Every entry has a single reader. Through 1.2.1 this object also carried NODE_ENV and DEBUG: "DEBUG"; nothing read either, and honouring a bare DEBUG would have changed behaviour for anyone who already sets it.

ERRORS

The CLI provides a comprehensive error hierarchy for different failure modes.

The classes below are the ones zudojs-cli exports from its package root. The scaffolding errors the commands themselves throw — CLIValidationError, CLIGenerationError, CLINotInProjectError and CLITemplateError — are owned by @zudojs/errors and are imported from there. CLINotInProjectError is what build, dev, add and, since 2.0, generate throw outside a Zudojs project.

Error Classes

Error Helpers

PACKAGE CONNECTIONS

SUGGESTED IMPROVEMENTS

API SUMMARY

Frontend Adapter Exports

COMPLETE EXPORT INDEX

Every name zudojs-cli exports from its package root at v2.1.0 — 183 in total, generated from the package’s own entry point rather than written by hand. The sections above explain the ones you reach for most; this is the exhaustive list, so nothing shipped is undocumented. Names not covered above are typically internal helpers and supporting types.