🚀 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:

1. Parse the spec(s)
2. Extract modules (tags)
3. Ask you which modules to generate
4. Produce TypeScript + Zod + Fetch clients
5. 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

1. Initialize templates (copies built-in templates to .vika/templates/):

   vika-cli templates init
   

2. List available templates:

   vika-cli templates list
   

3. Customize templates in .vika/templates/:

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

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

1. 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" }
     ]
   }
   

2. Generate all specs:

   vika-cli generate --all-specs
   

3. Generate specific spec:

   vika-cli generate --spec ecommerce
   

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

1. Fork
2. Create a feature branch
3. Make changes with tests
4. 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! 🚀