CLI Reference#

Every Mandu command-line entry point registered in @mandujs/cli at the version pinned by your project. The list below is generated from the command registry (commands/registry.ts); if a command is not in this page, it is not part of the supported CLI surface.

This list reflects v0.22 / v0.23. Check @mandujs/cli@0.23 release notes (and later) for any commands added after this snapshot.

Global behavior#

The binary is declared as #!/usr/bin/env bun — running Mandu commands under Node.js will fail. Argument parsing follows one rule:

• --flag value and --flag=value both work.
• Short flags are single-letter: -h, -q, -v, -d, -y (mapped to --help, --quiet, --verify, --diff, --yes).
• The first non-flag argument is the command; the second is the positional target (e.g. mandu generate page admin → command generate, subcommand page, target admin).

Global flags#

Exit codes#

Individual commands may exit with 0 specifically through exitOnSuccess — init, build, clean, info, generate, cache, middleware, session, auth, ws, collection, fix, review, ask, explain, scaffold, new, mcp, deploy, upgrade, desktop, completion.

Command index#

Project lifecycle#

mandu init#

Create a new project. Tailwind + shadcn/ui are included by default.

Exits 0 on success.

mandu dev#

Start the dev server. FS Routes and Guard are enabled by default.

Env vars: PORT, MANDU_PERF (set 1 for perf traces), MANDU_HDR (set 0 to disable HMR dynamic reload payloads).

mandu build#

Build client bundles for hydration.

Exits 0 on success.

mandu start#

Start production server. Requires a prior mandu build.

mandu preview#

Build and then start the production server in one step.

mandu clean#

Remove build artifacts under .mandu/client and .mandu/static.

mandu info#

Print project and environment information. No flags.

Quality gates#

mandu check#

Integrated FS Routes + Guard check. Honors CI=true for strict warning treatment.

mandu guard [subcommand]#

Architecture violation check. Default subcommand: arch.

Flags (forwarded to guard):

Env: CI=true enables agent/JSON output conventions.

mandu doctor#

Analyze Guard failures and suggest patches.

mandu fix#

Run Guard healing, diagnostics, and optional build verification.

mandu review#

Review changed files with guard and contract diagnostics.

Routes, contracts, OpenAPI#

mandu routes [subcommand]#

FS Routes management. Default: list.

Flags: --output, --verbose.

mandu contract <subcommand>#

Contract-first API development. No default — a subcommand is required.

mandu openapi <subcommand>#

Generate or serve an OpenAPI spec.

Code generation and scaffolds#

mandu generate [subcommand]#

Code generation. Subcommands: resource, page, api, feature, both.

mandu scaffold <type> [name] and mandu new <type> [name]#

Generate boilerplate. new is an alias for scaffold.

Types: middleware, ws, session, auth, collection.

mandu add <subcommand>#

Add features to an existing project.

mandu middleware init#

Generate middleware scaffolding. Flag: --preset.

mandu session init#

Generate session storage scaffolding. No flags.

mandu auth init#

Generate auth scaffolding and example routes. Flag: --strategy.

Env: JWT_SECRET (dev fallback mandu-dev-jwt-secret), SESSION_SECRET (dev fallback mandu-dev-secret), NODE_ENV (sets cookie secure).

mandu ws [name]#

Generate a WebSocket route scaffold.

mandu collection create [name]#

Create content collection scaffolding. Flag: --schema.

Tests and automation#

mandu test:auto#

ATE auto E2E generation/execution.

mandu test:watch#

Watch mode: re-run ATE for affected routes on file changes.

Terminated via SIGINT / SIGTERM.

mandu test:heal#

Generate ATE healing suggestions (no auto-commit). No flags.

Database#

mandu db <subcommand>#

Schema migrations.

Env: DATABASE_URL (primary), MANDU_DB_RESET_CONFIRM (destructive confirmation for reset). db dispatches to subcommand handlers which exit with their own explicit codes (EXIT_USAGE for invalid usage).

Observability and runtime#

mandu watch#

Real-time file watching.

mandu monitor#

Observability event monitor.

mandu brain <subcommand>#

Brain (sLLM) management.

mandu ask [...query]#

Ask the local Mandu assistant for codebase-aware guidance.

mandu explain [codeOrType]#

Explain a Guard rule or violation pattern.

Build, deploy, upgrade#

mandu cache <action>#

Cache management.

Flags: --tag, --all, --json.

mandu deploy#

Validate, build, and generate deployment artifacts.

mandu upgrade#

Check for or install the latest @mandujs/* package versions.

Change transactions, locks, MCP, desktop, completion#

mandu change <subcommand>#

Change transaction management.

mandu lock#

Lockfile management. Flags are validated by the command directly (not the top-level parser).

mandu mcp#

Run MCP tools from the terminal.

Extra flags are forwarded as the tool's argument payload.

mandu desktop [subcommand]#

Desktop targets. Default: scaffold.

Flags: --entry, --force. Env: MANDU_APP_TITLE.

mandu completion <shell>#

Output a shell completion script. Required positional: bash, zsh, or fish. Exits 1 if shell is missing or invalid.

Environment variables#

🤖 Agent Prompt#

Apply the guidance from the Mandu docs page at https://mandujs.com/docs/reference/cli to my project.

Summary of the page:
Canonical list of all mandu CLI subcommands registered in @mandujs/cli. Use this to know which commands exist, which flags are accepted, and which exit codes to expect. Do not invent commands not listed here.

Required invariants — must hold after your changes:
- The runnable command set is whatever @mandujs/cli registers in commands/registry.ts — this list reflects v0.22/v0.23
- Unknown commands print an error and exit with code 1; unknown subcommands do the same
- CLI entrypoint is the bun shebang (#!/usr/bin/env bun) — do not invoke with node
- Short flags are fixed: -h=--help, -q=--quiet, -v=--verify, -d=--diff, -y=--yes
- Subcommands that only make sense with a target (add, middleware, session, auth, collection, scaffold) exit with code 1 when called without their required subcommand

Then:
1. Make the change in my codebase consistent with the page.
2. Run `bun run guard` and `bun run check` to verify nothing
   in src/ or app/ breaks Mandu's invariants.
3. Show me the diff and any guard violations.