@kcflow/cli

KCFlow CLI Documentation 🚀

KCFlow is a TypeSafe End-to-End API Builder that allows you to generate Backend Code, Frontend SDKs, and API Documentation simultaneously from a Single Source of Truth.

📦 Installation

Install the CLI globally to access the kcflow command from anywhere:

npm install -g @kcflow/cli

Then, install the core library in your project:

npm install kcflow

⚡ Quick Start

1. Initialize Project

Create a configuration file and the initial folder structure.

kcflow init

This command generates:

• kcflow.config.json (Main configuration file)
• kcflow/spec/kcflow.spec.ts (API Specification file)

2. Define Your API

Edit kcflow/spec/kcflow.spec.ts to define your API endpoints.

import { defineResource, t } from 'kcflow';

export default defineResource({
  products: {
    getById: {
      method: 'GET',
      path: '/products/:id',
      body: t.object({
        id: t.string()
      })
    }
  }
});

3. Generate Code

Push your spec to the cloud to generate the SDK, Router, and Documentation.

kcflow gen

(Alias: kcflow push)

🛠 Commands Reference

kcflow init

Initializes KCFlow settings in the current project.

• Creates kcflow.config.json.
• Creates the kcflow/spec directory with a sample spec file.

kcflow generate (alias: gen, push)

Reads the config and spec files, sends them for processing, and writes the generated files to your local machine. Options:

• -c, --config <path>: Path to the config file (default: kcflow.config.json).
• -o, --output <path>: Output directory (default: as specified in config).

kcflow login <key>

Saves your API Key locally (for users with premium plans).

• Arguments: <key> Your API Key from the KCFlow Console.
• Example: kcflow login kcf_12345abcdef

⚙️ Configuration (kcflow.config.json)

The JSON file used to configure CLI behavior.

Property	Type	Description
clientType	`'axios'	'fetch'`
spec	string	Path to the Spec file (e.g., ./kcflow/spec/kcflow.spec.ts).
output.types	string	Path for TypeScript Definitions (.d.ts).
output.client	string	Path for the Frontend Client SDK.
output.router	string	Path for the Backend Router.
output.openapi	string	Path for the Swagger/OpenAPI JSON file.

Example:

{
  "clientType": "axios",
  "spec": "./kcflow/spec/kcflow.spec.ts",
  "output": {
    "types": "./src/generated/types.d.ts",
    "client": "./src/generated/client.ts",
    "router": "./src/generated/router.ts",
    "openapi": "./public/swagger.json"
  }
}

📝 Spec API (kcflow)

Used to define data structures (Schema) in your .spec.ts file.

defineResource(def)

The main function wrapper for all API definitions.

t (Type Helper)

A helper object for defining data types.

• t.string(): String value.
• t.number(): Numeric value.
• t.boolean(): Boolean value (true/false).
• t.object({ ... }): Object with nested properties.
• t.array(itemType): Array of a specific type.
• t.optional(field): Marks a field as optional.

Example usage of t:

body: t.object({
  username: t.string(),
  age: t.optional(t.number()), // Optional field
  tags: t.array(t.string())    // Array of strings
})

📂 Generated Output

Running kcflow gen will produce the following files:

• types.d.ts: Contains Interfaces for all Requests and Responses.
• client.ts: Ready-to-use Frontend SDK (call via client.resource.method()).
• router.ts: Backend Express Router (call via createRouter(app)).
• swagger.json: API Documentation in OpenAPI 3.0 standard.