🚀 vika-cli

A blazing-fast Rust-powered OpenAPI code generator that produces TypeScript types, Zod schemas, and Fetch clients — designed for real-world DX.

vika-cli is a blazing-fast, production-grade code generator that transforms any Swagger/OpenAPI specification into fully typed:

TypeScript interfaces
Zod validation schemas
Fetch-based API client functions
Module-organized output structure

Built in Rust for exceptional performance and reliability.

✨ Features

🚀 Ultra-fast Rust engine with deep schema resolution
📦 Module-based generation (grouped by Swagger tags)
🧬 TypeScript interfaces from OpenAPI schemas
🛡️ Zod validation schemas with constraints
🔌 Strongly-typed Fetch API client generation
🎯 Interactive module selection
🎛 Config-driven outputs (.vika.json)
💾 Spec caching for fast regeneration
🔄 Backup system for generated files
⚠️ Conflict detection for user-modified files
🔍 Inspect command for analyzing specs
🎨 Progress indicators and verbose logging
🧠 Handles: oneOf, anyOf, allOf, enums, recursion, circular refs
🌐 Supports HEAD, OPTIONS, PATCH, all HTTP verbs
🎨 Customizable templates (Tera-based) with user overrides
🛠 Multi-platform installers + CI/CD automation
🔀 Multi-spec support for microservices architectures

⚖️ Comparison With Other Tools

Tool	Types	Zod	Client	Rust Speed	Module Selection	Inspect	Cache
vika-cli	✅	✅	Fetch	⚡⚡⚡	✅	✅	✅
openapi-typescript	✅	❌	❌	❌	❌	❌	❌
Orval	⚠️	⚠️	Axios/Fetch	❌	❌	❌	❌
openapi-client-axios	❌	❌	Axios	❌	❌	❌	❌

Why choose vika-cli?

🚀 Rust-powered: Blazing fast schema resolution and code generation
🛡️ Complete validation: Native Zod schema generation with full constraint support
📦 Modular: Interactive module selection for selective generation
🔍 Built-in inspection: Analyze specs without generating code
💾 Smart caching: Fast regeneration with intelligent spec caching
🎯 Developer experience: Conflict detection, backups, and progress indicators

📦 Installation

macOS & Linux (recommended)

curl -fsSL https://github.com/MahdiZarrinkolah/vika-cli/releases/latest/download/install.sh | sh

Windows (PowerShell)

irm https://github.com/MahdiZarrinkolah/vika-cli/releases/latest/download/install.ps1 | iex

Cargo

cargo install vika-cli

From Source

git clone https://github.com/MahdiZarrinkolah/vika-cli
cd vika-cli
cargo build --release

🚀 Quick Start

1️ Initialize a project

vika-cli init

init now captures your first spec (name, path, schema/api outputs, module preferences) and writes .vika.json.
Need more specs later? Run vika-cli add each time you want to register another service.

2️ Generate code from your configured specs

# Interactive selection (default)
vika-cli generate

# Force a specific spec
vika-cli generate --spec ecommerce

# Regenerate everything
vika-cli generate --all-specs

Generation always uses the specs defined in .vika.json; the CLI no longer accepts raw spec paths. Remote URLs and local files are supported via each spec’s path.

Flags:

Flag	Description
`--spec <name>`	Generate specific spec (single or multi-spec mode)
`--all-specs`	Generate all specs (multi-spec mode only)
`--verbose`	Show detailed output
`--cache`	Use cached version of the spec
`--backup`	Backup files before overwriting
`--force`	Force overwrite conflicts

The generator will:

Parse the spec(s)
Extract modules (tags)
Ask you which modules to generate
Produce TypeScript + Zod + Fetch clients
Show a detailed generation summary table

3️ Update previously generated modules

vika-cli update

4️ Inspect a specification (no generation)

Single Spec Mode

vika-cli inspect --spec ./swagger.yaml

Multi-Spec Mode

# Inspect all specs
vika-cli inspect --all-specs

# Inspect specific spec by name
vika-cli inspect --spec ecommerce

Examples:

# Single spec mode
vika-cli inspect --spec ./swagger.yaml --module products
vika-cli inspect --spec ./swagger.yaml --schemas
vika-cli inspect --spec ./swagger.yaml --json

# Multi-spec mode
vika-cli inspect --spec admin --schemas
vika-cli inspect --all-specs --json

🧠 How It Works

vika-cli uses a robust generation pipeline:

1. Spec Parsing

Reads OpenAPI 3.x JSON/YAML.

2. Module Extraction

Groups endpoints by Swagger tags.

3. Schema Resolution

Resolves:

$ref
Circular dependencies
Recursive models
oneOf / anyOf / allOf
Enum values
Nullable fields

4. Code Generation

Produces:

TypeScript interfaces
Zod schemas with constraints
Fetch-based API clients

5. Safe Writing

Writes only changed files
Detects conflicts
Optional backup mode
Generates index/barrel files
Optional Prettier/Biome post-formatting

⚙️ Configuration (`.vika.json`)

vika-cli now uses a single, always-multi-spec configuration model. Every spec lives inside the specs array and declares its own schema/API/module configuration.

{
  "$schema": "https://raw.githubusercontent.com/vikarno/vika-cli/main/schema/vika-config.schema.json",
  "root_dir": "src",
  "generation": {
    "enable_cache": true,
    "enable_backup": false,
    "conflict_strategy": "ask"
  },
  "specs": [
    {
      "name": "ecommerce",
      "path": "http://localhost:3000/swagger-ecommerce.json",
      "schemas": {
        "output": "src/schemas/ecommerce",
        "naming": "PascalCase"
      },
      "apis": {
        "output": "src/apis/ecommerce",
        "style": "fetch",
        "base_url": "https://api.example.com",
        "header_strategy": "consumerInjected"
      },
      "modules": {
        "ignore": [],
        "selected": ["orders", "payments", "users"]
      }
    }
  ]
}

Global settings

Key	Description
`root_dir`	Base directory for generated files (`src` by default).
`generation.enable_cache`	Cache parsed specs for faster re-runs (default `true`).
`generation.enable_backup`	Create timestamped backups before overwriting (default `false`).
`generation.conflict_strategy`	How to handle modified files: `ask`, `force`, or `skip`.

Spec entry reference

Key	Description
`specs[].name`	Unique spec identifier (kebab-case recommended).
`specs[].path`	Local file path or URL to the OpenAPI document.
`specs[].schemas.output`	Destination folder for TypeScript + Zod output for this spec.
`specs[].schemas.naming`	Naming convention (`PascalCase`, `camelCase`, `snake_case`, `kebab-case`).
`specs[].apis.output`	Output folder for this spec’s API clients.
`specs[].apis.style`	Client style. Currently only `fetch`.
`specs[].apis.base_url`	Optional base URL baked into generated clients.
`specs[].apis.header_strategy`	`consumerInjected`, `bearerToken`, or `fixed`.
`specs[].modules.ignore`	Tags to skip entirely.
`specs[].modules.selected`	Tags to generate. Filled automatically after the first run or when using interactive prompts.

Add new specs via vika-cli add (appends to specs). vika-cli init only creates the first entry, keeping multi-spec workflows predictable.

Full reference: docs/configuration.md

🎨 Customizing Templates

vika-cli uses Tera templates for code generation. You can customize the output format by overriding built-in templates.

Quick Start

Initialize templates (copies built-in templates to .vika/templates/):
```
vika-cli templates init
```
List available templates:
```
vika-cli templates list
```

Customize templates in .vika/templates/:

# Edit .vika/templates/type-interface.tera
# Edit .vika/templates/api-client-fetch.tera
# etc.

Regenerate code - your custom templates will be used automatically:
```
vika-cli generate --spec your-spec.yaml
```

Template Files

type-interface.tera - TypeScript interface generation
type-enum.tera - TypeScript enum generation
zod-schema.tera - Zod schema generation
api-client-fetch.tera - API client function generation

Template Resolution: User templates in .vika/templates/ override built-in templates automatically.

Full documentation: docs/templates.md

🧱 Output Structure

Single Spec Mode

📁 src/
│
├── 📁 schemas/
│   │
│   ├── 📁 products/
│   │   ├── 📄 types.ts          # TypeScript interfaces
│   │   ├── 📄 schemas.ts        # Zod validation schemas
│   │   └── 📄 index.ts          # Barrel exports
│   │
│   ├── 📁 users/
│   │   ├── 📄 types.ts
│   │   ├── 📄 schemas.ts
│   │   └── 📄 index.ts
│   │
│   └── 📁 orders/
│       ├── 📄 types.ts
│       ├── 📄 schemas.ts
│       └── 📄 index.ts
│
└── 📁 apis/
    │
    ├── 📁 runtime/               # Runtime HTTP client with ApiResult types
    │   ├── 📄 types.ts           # ApiResult type definitions
    │   ├── 📄 http-client.ts     # VikaClient class with middleware, retries, auth
    │   └── 📄 index.ts           # Runtime exports
    │
    ├── 📁 products/
    │   └── 📄 index.ts           # API client functions
    │
    ├── 📁 users/
    │   └── 📄 index.ts
    │
    └── 📁 orders/
        └── 📄 index.ts

Multi-Spec Mode (Microservices)

When using specs array, output is organized by spec name:

📁 src/
│
├── 📁 schemas/
│   │
│   ├── 📁 ecommerce/             # From ecommerce spec
│   │   ├── 📁 products/
│   │   │   ├── 📄 types.ts
│   │   │   ├── 📄 schemas.ts
│   │   │   └── 📄 index.ts
│   │   └── 📁 orders/
│   │       └── ...
│   │
│   ├── 📁 admin/                 # From admin spec
│   │   ├── 📁 users/
│   │   └── 📁 permissions/
│   │
│   └── 📁 public/                # From public spec
│       └── 📁 catalog/
│
└── 📁 apis/
    │
    ├── 📁 runtime/               # Runtime HTTP client with ApiResult types
    │   ├── 📄 types.ts           # ApiResult type definitions
    │   ├── 📄 http-client.ts     # VikaClient class with middleware, retries, auth
    │   └── 📄 index.ts           # Runtime exports
    │
    ├── 📁 ecommerce/             # From ecommerce spec
    │   ├── 📁 products/
    │   │   └── 📄 index.ts
    │   └── 📁 orders/
    │       └── 📄 index.ts
    │
    ├── 📁 admin/                 # From admin spec
    │   └── 📁 users/
    │       └── 📄 index.ts
    │
    └── 📁 public/                # From public spec
        └── 📁 catalog/
            └── 📄 index.ts

This structure ensures:

✅ Isolation: Each spec's generated code is separated
✅ No conflicts: Different specs can have modules with the same name
✅ Clear organization: Easy to identify which service generated which code

File types:

🟦 types.ts - TypeScript type definitions (ProductDto, UserProfile, etc.)
🟨 schemas.ts - Zod validation schemas (ProductDtoSchema, etc.)
🟩 index.ts - Barrel exports and API client functions
🟧 http.ts - Core HTTP client with fetch wrapper

📘 Example Output

TypeScript Types

export interface ProductDto {
  id: string;
  price: number;
  title: string;
}

Zod Schema

export const ProductDtoSchema = z.object({
  id: z.string(),
  price: z.number(),
  title: z.string(),
});

Fetch API Client

export const getProduct = async (id: string): Promise<ProductDto> =>
  http.get(`/products/${id}`);

🧩 Advanced Features

Multi-Spec Support (Microservices)

vika-cli supports generating code from multiple OpenAPI specifications in a single project. This is ideal for microservices architectures where different services expose separate APIs.

Benefits

🔀 Multiple Services: Generate code for all your microservices in one command
📦 Isolated Output: Each spec's code is organized in separate directories
🎯 Selective Generation: Generate all specs or target specific ones
🔄 Unified Workflow: Single config file manages all specs

Usage

Configure multiple specs in .vika.json:

{
  "specs": [
    { "name": "ecommerce", "path": "http://localhost:3000/swagger-ecommerce.json" },
    { "name": "admin", "path": "http://localhost:3000/swagger-admin.json" },
    { "name": "public", "path": "http://localhost:3000/swagger-public.json" }
  ]
}

Generate all specs:
```
vika-cli generate --all-specs
```
Generate specific spec:
```
vika-cli generate --spec ecommerce
```

Interactive selection (default):

vika-cli generate
# Prompts: "Which spec do you want to generate?"

Spec Naming Rules

Use kebab-case (e.g., ecommerce, order-service, user-api)
Names must be unique within the specs array
Names are used in directory paths: apis/{spec_name}/{module}/

⚡ Caching

vika-cli generate --cache

Each spec is cached independently using its name as part of the cache key.

🛡 Backup Mode

vika-cli generate --backup

Backups stored in:

.vika-backup/<timestamp>/

⚠ Conflict Detection

Warns if manually modified files would be overwritten.

🧪 Snapshot Testing

Using insta for generator correctness.

🧱 Architecture Overview

Commands: init, generate, update, inspect
Generator Core: TS/Zod/API client generation
Schema Resolver: Handles refs, unions, recursion
Writer System: Diffs, backups, conflict detection
Config System: Load & validate .vika.json
Error System: Structured typed errors
Utilities: caching, formatting, progress indicators

Details: docs/architecture.md

🔄 Development & Release

CI includes:

cargo fmt
cargo clippy
Unit tests
Snapshot tests
Multi-platform builds

Releases

cargo release patch

Semantic versioning applies:

MAJOR = breaking changes
MINOR = new features
PATCH = fixes

See: CHANGELOG.md

🤝 Contributing

Fork
Create a feature branch
Make changes with tests
Submit a PR

Guide: docs/contributing.md

📜 License

MIT

🔗 Links

🔗 GitHub: https://github.com/MahdiZarrinkolah/vika-cli
📚 Documentation: /docs
🐞 Issue Tracker: https://github.com/MahdiZarrinkolah/vika-cli/issues

🎉 Thank You

vika-cli is now a fully production-grade OpenAPI codegen tool.

Enjoy building! 🚀

vika-cli 1.4.0

🚀 vika-cli

A blazing-fast Rust-powered OpenAPI code generator that produces TypeScript types, Zod schemas, and Fetch clients — designed for real-world DX.

✨ Features

⚖️ Comparison With Other Tools

📦 Installation

macOS & Linux (recommended)

Windows (PowerShell)

Cargo

From Source

🚀 Quick Start

1️ Initialize a project

2️ Generate code from your configured specs

3️ Update previously generated modules

4️ Inspect a specification (no generation)

Single Spec Mode

Multi-Spec Mode

🧠 How It Works

1. Spec Parsing

2. Module Extraction

3. Schema Resolution

4. Code Generation

5. Safe Writing

⚙️ Configuration (.vika.json)

Global settings

Spec entry reference

🎨 Customizing Templates

Quick Start

Template Files

🧱 Output Structure

Single Spec Mode

Multi-Spec Mode (Microservices)

📘 Example Output

TypeScript Types

Zod Schema

Fetch API Client

🧩 Advanced Features

Multi-Spec Support (Microservices)

Benefits

Usage

Spec Naming Rules

⚡ Caching

🛡 Backup Mode

⚠ Conflict Detection

🧪 Snapshot Testing

🧱 Architecture Overview

🔄 Development & Release

CI includes:

Releases

🤝 Contributing

📜 License

🔗 Links

🎉 Thank You

⚙️ Configuration (`.vika.json`)