Skip to main content
The tsoa CLI provides three commands for generating OpenAPI specifications and route handlers. Each command accepts various flags to override configuration file settings.

​
Command Syntax

tsoa <command> [options]
Use tsoa --help to see all available commands, or tsoa <command> --help for command-specific options.

​
spec

Generates an OpenAPI specification file from your TypeScript controllers. 
tsoa spec [options]

​
What it does

1

Scan Controllers

Reads your TypeScript controllers starting from the entry file or using controller path globs
2

Extract Metadata

Analyzes decorators (@Route, @Get, @Post, etc.) and TypeScript types to extract API metadata
3

Generate Specification

Creates an OpenAPI 2.0, 3.0, or 3.1 specification file (JSON or YAML format)
4

Write Output

Saves the specification to the configured output directory

​
Options

​
--configuration
string
default:"tsoa.json"
Path to the tsoa configuration file. Supports .json, .yaml, .yml, .js, and .cjs formats.
tsoa spec --configuration config/tsoa.production.json
tsoa spec -c tsoa.yaml
​
--basePath
string
Override the base API path defined in configuration. This is prepended to all route paths.
# Override basePath to /v2
tsoa spec --basePath /v2

# Remove basePath
tsoa spec --basePath ""
​
--host
string
Override the API host defined in configuration. Used in OpenAPI 2.0 specs.
tsoa spec --host api.example.com
tsoa spec --host localhost:8080
​
--yaml
boolean
Force YAML output format instead of JSON.
tsoa spec --yaml
​
--json
boolean
Force JSON output format instead of YAML.
tsoa spec --json

​
Examples

tsoa spec

​
Output

Creates a specification file at: 
{spec.outputDirectory}/{spec.specFileBaseName}.{json|yaml}
Default: dist/swagger.json
The spec command only generates the OpenAPI specification. To also generate route handlers, use spec-and-routes.

​
routes

Generates route handler files with built-in validation for your chosen middleware framework. 
tsoa routes [options]

​
What it does

1

Scan Controllers

Reads your TypeScript controllers to understand routing requirements
2

Generate Route Handlers

Creates middleware-specific route registration code (Express, Koa, or Hapi)
3

Add Validation

Includes runtime validation based on TypeScript types and decorators
4

Wire Dependencies

Integrates authentication and IoC modules if configured

​
Options

​
--configuration
string
default:"tsoa.json"
Path to the tsoa configuration file.
tsoa routes --configuration tsoa.json
tsoa routes -c config/tsoa.yaml
​
--basePath
string
Override the base API path for route generation.
tsoa routes --basePath /api/v1

​
Examples

tsoa routes

​
Output

Creates a routes file at: 
{routes.routesDir}/{routes.routesFileName}
Default: src/routes.ts The generated file includes:
  • Route registration for your middleware framework
  • Request/response validation
  • Type coercion and sanitization
  • Authentication integration
  • Error handling
import { RegisterRoutes } from './routes';

const app = express();
app.use(express.json());

// Register tsoa routes
RegisterRoutes(app);

app.listen(3000);
The generated routes file should be imported and registered in your application after generating it.

​
spec-and-routes

Generates both OpenAPI specification and route handlers in a single pass. This is more efficient than running spec and routes separately. 
tsoa spec-and-routes [options]

​
Why use this command?

Performance

Scans controllers once instead of twice, significantly faster for large projects

Consistency

Ensures spec and routes are generated from identical metadata

Simplicity

Single command for complete code generation

CI/CD Friendly

Simpler build scripts with one command

​
Options

Combines all options from both spec and routes commands:
​
--configuration
string
default:"tsoa.json"
Path to the tsoa configuration file.
tsoa spec-and-routes -c tsoa.json
​
--basePath
string
Override the base API path for both spec and routes.
tsoa spec-and-routes --basePath /api/v1
​
--host
string
Override the API host in the generated specification.
tsoa spec-and-routes --host api.example.com
​
--yaml
boolean
Generate spec in YAML format.
tsoa spec-and-routes --yaml
​
--json
boolean
Generate spec in JSON format.
tsoa spec-and-routes --json

​
Examples

tsoa spec-and-routes

​
Output

Generates both:
  1. Specification file: {spec.outputDirectory}/{spec.specFileBaseName}.{json|yaml}
  2. Routes file: {routes.routesDir}/{routes.routesFileName}
Use spec-and-routes as your default command unless you specifically need only the spec or only the routes.

​
Global Options

These options work with any command:
​
--help, -h
boolean
Display help information.
tsoa --help
tsoa spec --help
tsoa routes --help
​
--version
boolean
Display the tsoa version.
tsoa --version

​
Exit Codes

The CLI uses standard exit codes:
CodeMeaningCommon Causes
0SuccessGeneration completed without errors
1ErrorConfiguration errors, invalid TypeScript, missing files

​
Handling Errors in Scripts

#!/bin/bash

if tsoa spec-and-routes; then
  echo "✓ Generation successful"
  npm run build
else
  echo "✗ Generation failed"
  exit 1
fi

​
Common Workflows

​
Development Mode

package.json
{
  "scripts": {
    "gen": "tsoa spec-and-routes",
    "dev": "npm run gen && nodemon src/server.ts",
    "dev:watch": "nodemon --watch src --ext ts --exec 'npm run gen && ts-node src/server.ts'"
  }
}

​
Build Pipeline

package.json
{
  "scripts": {
    "clean": "rm -rf dist",
    "gen": "tsoa spec-and-routes",
    "compile": "tsc",
    "build": "npm run clean && npm run gen && npm run compile",
    "prebuild": "npm run gen"
  }
}

​
Testing

package.json
{
  "scripts": {
    "pretest": "tsoa spec-and-routes",
    "test": "jest",
    "test:api": "npm run gen && newman run tests/postman-collection.json"
  }
}

​
Troubleshooting

tsoa: command not found
Solutions:
  • Use npx tsoa instead of tsoa
  • Run via npm script: npm run tsoa:gen
  • Install globally: npm install -g tsoa (not recommended)
No config file found at 'tsoa.json'
Solutions:
  • Create a tsoa.json in your project root
  • Specify the path: tsoa spec -c path/to/config.json
  • Use a different format: tsoa.yaml or tsoa.js
Solutions:
  • Use spec-and-routes instead of running commands separately
  • Add more paths to ignore in configuration
  • Use controllerPathGlobs instead of scanning from entryFile
  • Ensure TypeScript skipLibCheck: true in tsconfig.json
Solutions:
  • Ensure your project compiles: tsc --noEmit
  • Check compilerOptions in tsoa.json matches tsconfig.json
  • Fix any type errors in controller files

​
Next Steps

Configuration

Learn about all configuration options

tsoa.json Reference

Complete configuration schema

Build docs developers (and LLMs) love

Get started for freeTalk to us