CLI Reference

tsgonest provides two subcommands: build for production compilation and dev for watch-mode development. If no subcommand is given, build is assumed.

tsgonest build

Compiles TypeScript via tsgo, generates companion files, writes the manifest, and produces the OpenAPI document.

tsgonest build [flags]

Flags

Pipeline

When you run tsgonest build, the following steps execute in order:

1. Resolve config — Load tsgonest.config.json from --config or auto-detect in the working directory.
2. Parse tsconfig — Read tsconfig.json (or the path given by --project) using tsgo's native JSONC parser.
3. Create program — Build a tsgo program (incremental if configured in tsconfig).
4. Type-check — Gather diagnostics. If errors exist and --no-check is not set, exit with code 1.
5. Emit JavaScript — Write compiled JS to the output directory.
6. Check cache — If the post-processing cache is valid (source files unchanged), skip steps 7-9.
7. Generate companions — Walk the AST, extract type metadata, generate *.tsgonest.js and *.tsgonest.d.ts files.
8. Write manifest — Generate __tsgonest_manifest.json with companion and route mappings.
9. Generate OpenAPI — Static analysis of NestJS controllers produces openapi.json.
10. Copy assets — If --assets is set, copy non-TS files to the output directory.

Examples

# Default build (uses tsconfig.json + auto-detected config)
tsgonest build

# Custom tsconfig
tsgonest build --project tsconfig.build.json

# Clean build
tsgonest build --clean

# Skip type checking for faster builds
tsgonest build --no-check

# Explicit config path
tsgonest build --config configs/tsgonest.config.json -p tsconfig.build.json

# Dump type metadata for debugging
tsgonest build --dump-metadata

Exit codes

tsgonest dev

Watch-mode development server. Watches source files, rebuilds on changes, and restarts your Node.js process.

tsgonest dev [flags] [-- node-args...]

Flags

Behavior

1. Initial build — Runs a full tsgonest build on startup.
2. Start process — Launches node dist/<entry>.js (or the custom --exec command).
3. Watch — Monitors src/ (or sourceRoot from config) for file changes.
4. Rebuild — On file change, clears the terminal, runs an incremental build, and restarts the process.
5. Manual restart — Type rs + Enter to trigger a manual rebuild and restart (when manualRestart is enabled in config).

Passthrough arguments

Arguments after -- are passed directly to the Node.js process:

# Pass --inspect-brk to Node.js
tsgonest dev -- --inspect-brk

# Pass environment variables
tsgonest dev -- --max-old-space-size=4096

Examples

# Basic watch mode
tsgonest dev

# With custom entry point
tsgonest dev --entry src/main.ts

# With environment file
tsgonest dev --env-file .env --env-file .env.local

# With Node.js debugger
tsgonest dev --debug

# With custom build config
tsgonest dev --project tsconfig.build.json --config tsgonest.config.json

# Don't clear terminal on rebuild
tsgonest dev --preserveWatchOutput

Implicit build

If you run tsgonest without a subcommand but with flags that start with -, it is treated as tsgonest build:

# These are equivalent:
tsgonest build --project tsconfig.build.json
tsgonest --project tsconfig.build.json

Version

tsgonest --version
# tsgonest v0.1.1