CLI Reference

Commands

The create-freestyle-fetch provides a single generate command for creating API clients.

`generate`

Generate a type-safe API client from an OpenAPI specification.

create-freestyle-fetch generate [options]

Options

Option	Alias	Type	Required	Description
`--input <path>`	`-i`	string	Yes	Path to the OpenAPI specification file (JSON or YAML). The generator automatically detects the format based on the file extension.
`--output <dir>`	`-o`	string	Yes	Directory where generated files will be saved

Note: Both .json and .yaml/.yml files are supported. No additional flags are required.

Examples

A. Basic Generation

Generate client files from a local specification:

create-freestyle-fetch generate \
  --input ./api-spec.yaml \
  --output ./src/api

B. Using Relative Paths

Paths are resolved relative to the current working directory:

create-freestyle-fetch generate \
  -i ../specs/api.json \
  -o ./generated

C. With `npx`

Run the generator without installation:

npx create-freestyle-fetch generate \
  --input ./openapi.json \
  --output ./src/generated

Output Files

The generate command creates four files in the output directory:

A. `models.ts`

Contains Zod schemas for all components defined in your OpenAPI specification:

import { z } from 'zod'

export const User = z.object({
  id: z.string(),
  name: z.string(),
  email: z.email()
})

export type UserModel = z.infer<typeof User>

B. `api.ts`

Contains the type-safe router factory with all API endpoints:

import { f } from '@freestylejs/fetch'
import { z } from 'zod'
import * as Model from './models'
import { createAuthMiddleware, AuthConfig } from './auth'

export const createClient = (config: { baseUrl?: string, auth?: AuthConfig } = {}) => {
    // ... middleware setup
    return f.router({
        baseUrl: config.baseUrl || 'https://api.example.com',
        middleware
    }, {
        users: {
            $userId: {
                GET: f.builder()
                    .def_json()
                    .def_response(async ({ json }) => Model.User.parse(await json()))
            }
        }
    })
}

C. `auth.ts`

Contains authentication configuration types and middleware factory:

import { f, type Middleware } from '@freestylejs/fetch'

export interface AuthConfig {
    bearerAuth?: {
        token: string | (() => Promise<string>)
    }
}

export const createAuthMiddleware = (config: AuthConfig) => {
    // ... middleware implementation
}

D. `index.ts`

Re-exports all generated code for convenience:

export * from './api'
export * from './models'
export * from './auth'

Error Handling

The CLI provides clear error messages for common issues:

A. Invalid Specification

If the OpenAPI file is invalid or cannot be parsed:

✗ Error parsing OpenAPI specification

  File: ./api-spec.yaml:42
  Issue: bad indentation of a mapping entry

  💡 Suggestion: YAML requires consistent indentation (use spaces, not tabs)

B. Missing File

If the input file does not exist:

✗ Error parsing OpenAPI specification

  File: ./api-spec.json
  Issue: ENOENT: no such file or directory

  💡 Suggestion: File not found. Check that "./api-spec.json" exists and is accessible

C. Validation Warnings

The CLI may output warnings for non-critical issues:

⚠ Validation Warnings:

  • Missing operationId for GET operation. A generated ID will be used.
    Path: GET /users

D. Output Directory Issues

The generator creates the output directory if it doesn't exist. Existing files are overwritten.

Best Practices

A. Version Control

Add generated files to .gitignore and regenerate them during your build process:

# .gitignore
src/generated/

{
  "scripts": {
    "generate": "create-freestyle-fetch generate -i ./spec.json -o ./src/generated",
    "prebuild": "npm run generate"
  }
}

B. CI/CD Integration

Integrate generation into your CI/CD pipeline:

# .github/workflows/build.yml
steps:
  - name: Generate API Client
    run: |
      npx create-freestyle-fetch generate \
        --input ./openapi.json \
        --output ./src/generated
  
  - name: Build Application
    run: npm run build

Getting Started - Installation and basic usage
Authentication - Configure auth credentials
Generated Code - Understanding the output

CLI Reference

On this page