CLI Reference

tsgonest provides several subcommands: build for production compilation, check for fast type checking without emit, dev for watch-mode development, and openapi for standalone OpenAPI spec generation. If no subcommand is given, build is assumed.

tsgonest build

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

tsgonest build [flags]

Flags

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 check

Type check your project and run tsgonest-specific analysis without emitting any files. Catches both TypeScript errors and tsgonest-specific warnings (invalid parameter types, unsupported decorator patterns, anonymous generic arguments, etc.).

tsgonest check [flags]

Flags

What it checks

1. TypeScript diagnostics — syntax and semantic errors (same as tsc --noEmit)
2. Controller analysis — validates NestJS decorators, parameter types, and route definitions (14 warning kinds including param-non-scalar, query-complex-type, unsupported-dynamic-route-path, etc.)
3. Type walker — detects anonymous generic type arguments that can't be named in OpenAPI

Watch mode

Use --watch for continuous checking during development:

tsgonest check --watch

On each file save the full check pipeline re-runs. Since check skips emit, this is fast enough for interactive use.

Examples

# One-shot check
tsgonest check

# Continuous watch
tsgonest check --watch

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

# Skip type checking for tsgonest-only analysis
tsgonest check --no-check

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

tsgonest openapi

Generate OpenAPI documents without running a full build. Skips TypeScript emit, companion file generation, SDK generation, and asset copying. Useful for CI/CD pipelines, documentation publishing, and API diff checks.

tsgonest openapi [flags]

Flags

Examples

# Generate from default config
tsgonest openapi

# Generate only the "public" output from a multi-output config
tsgonest openapi --name public

# Override output path
tsgonest openapi --output dist/api-spec.json

# Skip type checking for faster generation
tsgonest openapi --no-check

# Use a specific config
tsgonest openapi --config tsgonest.public.config.ts

Path Alias Resolution

tsgonest automatically resolves TypeScript path aliases (paths in tsconfig.json) in the compiled output. Import statements like @app/users/user.dto are rewritten to relative paths in the emitted JavaScript — no additional tooling (like tsconfig-paths or tsc-alias) required.

{
  "compilerOptions": {
    "paths": {
      "@app/*": ["src/*"],
      "@shared/*": ["src/shared/*"]
    }
  }
}

// Source
import { UserDto } from '@app/users/user.dto';

// Compiled output — path alias resolved automatically
import { UserDto } from './users/user.dto.js';

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