@testurio/cli

CLI for Testurio - generate type-safe Zod schemas and service interfaces from OpenAPI specs and .proto files.

Installation

npm install @testurio/cli --save-dev
# or
pnpm add @testurio/cli --save-dev

Quick Start

# Create a starter testurio.config.ts
testurio init

# Generate schemas from config
testurio generate

# Or pass files directly (type auto-detected from extension)
testurio generate api.yaml service.proto

# Directory input (scans for supported files)
testurio generate ./api/

# With output directory
testurio generate api.yaml service.proto -o ./generated/

Commands

generate

Generate TypeScript types and Zod schemas from API specifications.

testurio generate [inputs...] [options]

| Argument / Option | Description | | --------------------- | ------------------------------------------------------------------------------------ | | [inputs...] | Input files or directories (.yaml, .yml, .json for OpenAPI; .proto for gRPC) | | -c, --config <path> | Path to config file | | -o, --output <path> | Output file or directory (default: {input}.schema.ts) | | --quiet | Suppress non-error output | | --verbose | Enable debug output |

When inputs are provided, the CLI runs in inline mode — no config file needed. When omitted, it loads the config file.

Examples:

# Single file
testurio generate openapi.yaml

# Multiple files
testurio generate api.yaml user.proto chat.proto

# Directory (all supported files)
testurio generate ./specs/

# Custom output
testurio generate api.yaml -o ./generated/api.schema.ts

# Multiple files with output directory
testurio generate api.yaml service.proto -o ./generated/

init

Create a starter testurio.config.ts in the current directory.

testurio init

Configuration

Create a testurio.config.ts (or .js, .mjs, .cjs) in your project root:

import { defineConfig } from '@testurio/cli';

export default defineConfig({
  generate: {
    sources: [
      {
        input: './api/openapi.yaml',
      },
      {
        input: './proto/user-service.proto',
        options: {
          services: ['UserService'],
        },
      },
      {
        input: './specs/',
        output: './generated/',
      },
    ],
  },
});

OpenAPI Source Options

| Option | Type | Default | Description | | ----------------------------- | --------- | ------------------ | ----------------------------------------------- | | input | string | — | Path to OpenAPI spec (.yaml, .yml, .json) | | output | string | {input}.schema.ts | Output file path | | options.zod.strict.response | boolean | — | Enable strict mode for response schemas | | options.zod.strict.body | boolean | — | Enable strict mode for body schemas | | options.zod.coerce.query | boolean | — | Enable coercion for query parameters | | options.zod.coerce.params | boolean | — | Enable coercion for path parameters | | options.operationsMap | boolean | true | Generate operations map | | options.errorSchemaName | string | — | Name for error response schema |

gRPC Source Options

| Option | Type | Default | Description | | ----------------------------- | -------------------- | -------------------- | ---------------------------------------- | | input | string \| string[] | — | Path(s) to .proto file(s) | | output | string | {input}.schema.ts | Output file path | | options.services | string[] | all | Filter to specific service names | | options.streaming | boolean | true | Generate streaming types | | options.includeDirs | string[] | — | Additional proto include directories | | options.metadata.optionName | string | "required_headers" | Custom method option for metadata typing |

Auto-Detection

Source type is determined automatically from file extension — no type field needed in config:

| Extension | Source Type | | ------------------------ | ----------- | | .yaml, .yml, .json | OpenAPI | | .proto | gRPC |

Generated Output

The generator produces TypeScript files with Zod schemas, service interfaces, and protocol schema bridges compatible with Testurio protocols.

Schema-First Usage (Recommended)

The generated {serviceName}Schema export provides runtime validation and automatic type inference:

// Generated from OpenAPI → schema-first (types inferred automatically)
import { petStoreSchema } from './petstore.schema';
const protocol = new HttpProtocol({ schema: petStoreSchema });

// Generated from .proto → schema-first
import { userServiceSchema } from './service.schema';
const protocol = new GrpcUnaryProtocol({ protoPath: 'service.proto', schema: userServiceSchema });

Legacy Usage (Explicit Generic)

The generated TypeScript interfaces are still available for explicit generic usage without runtime validation:

// OpenAPI — explicit generic, no runtime validation
import type { PetStore } from './petstore.schema';
const protocol = new HttpProtocol<PetStore>();

// gRPC — explicit generic
import type { UserService } from './service.schema';
const protocol = new GrpcUnaryProtocol<UserService>({ protoPath: 'service.proto' });

Programmatic API

The package exports its core utilities for programmatic usage:

import {
  defineConfig,
  detectSourceType,
  resolveInputs,
  loadConfig,
  createCli,
  buildSourcesFromInputs,
  resolveOutputPath,
  SUPPORTED_EXTENSIONS,
  OPENAPI_EXTENSIONS,
  PROTO_EXTENSIONS,
} from '@testurio/cli';

License

MIT