Skip to main content
The tsoa CLI is the primary tool for generating OpenAPI specifications and route handlers from your TypeScript controllers. It provides a simple, command-driven workflow for keeping your API documentation and routing logic in sync with your code.

​
Installation

Install tsoa as a development dependency in your project: 
npm install tsoa --save-dev

​
Quick Start

Once installed, you can use the tsoa CLI through npm scripts or directly via npx: 
# Add to package.json scripts
"scripts": {
  "tsoa:spec": "tsoa spec",
  "tsoa:routes": "tsoa routes",
  "tsoa:gen": "tsoa spec-and-routes"
}

​
Core Commands

tsoa provides three primary commands:

spec

Generate OpenAPI specification from your TypeScript controllers

routes

Generate Express/Koa/Hapi route handlers with validation

spec-and-routes

Generate both spec and routes in a single pass (faster)

​
Configuration File

All CLI commands rely on a configuration file (default: tsoa.json) that defines:
  • Entry points to your API controllers
  • Output directories for generated files
  • OpenAPI specification options
  • Route generation settings
  • Middleware selection (Express, Koa, or Hapi)
{
  "entryFile": "src/app.ts",
  "noImplicitAdditionalProperties": "throw-on-extras",
  "spec": {
    "outputDirectory": "dist",
    "specVersion": 3
  },
  "routes": {
    "routesDir": "src",
    "middleware": "express"
  }
}

​
Workflow Integration

​
Development Workflow

For development, regenerate specs and routes when controllers change: 
# Watch mode (using nodemon or similar)
nodemon --watch src --exec "npm run tsoa:gen && npm start"

​
Build Pipeline

Integrate tsoa generation into your build process:
package.json
{
  "scripts": {
    "prebuild": "tsoa spec-and-routes",
    "build": "tsc",
    "prestart": "npm run build",
    "start": "node dist/app.js"
  }
}

​
CI/CD Integration

Validate that generated files are up-to-date in CI:
.github/workflows/ci.yml
- name: Generate tsoa files
  run: npm run tsoa:gen

- name: Check for changes
  run: |
    if [[ -n $(git status -s) ]]; then
      echo "Generated files are out of date"
      exit 1
    fi

​
Common Flags

All commands support these common options:
​
--configuration
string
default:"tsoa.json"
Path to the tsoa configuration file
tsoa spec --configuration config/tsoa.production.json
​
--basePath
string
Override the base API path from configuration
tsoa spec --basePath /api/v2
​
--help
boolean
Display help information for any command
tsoa --help
tsoa spec --help

​
Output Files

Depending on your configuration, tsoa generates:

​
Specification Files

  • swagger.json or swagger.yaml - OpenAPI specification
  • Location determined by spec.outputDirectory and spec.specFileBaseName

​
Route Files

  • routes.ts - Generated route handlers with validation
  • Location determined by routes.routesDir and routes.routesFileName
  • Includes type-safe request/response handling
  • Built-in validation middleware
Generated files should typically be committed to version control, as they’re part of your application’s runtime behavior.

​
Error Handling

The CLI provides detailed error messages for common issues: 
No config file found at 'tsoa.json'
Solution: Create a tsoa.json file or specify a custom path with --configuration
EntryFile not found: src/app.ts - please check your tsoa config
Solution: Ensure the entryFile path is correct and the file exists
Missing outputDirectory: configuration must contain output directory
Solution: Add spec.outputDirectory or routes.routesDir to your config

​
Next Steps

Commands Reference

Detailed documentation for each CLI command

Configuration Guide

Complete configuration options and examples

tsoa.json Schema

Full configuration schema reference

Quick Start

Get started with a complete example

Build docs developers (and LLMs) love

Get started for freeTalk to us