CLI

cmd-ipc includes a CLI for generating TypeScript schemas from remote services. This enables type-safe client development without sharing code between projects.

Installation

The CLI is included with the main package:

npm install @coralstack/cmd-ipc

You can run it via npx:

npx cmd-ipc --help

Or add it to your package.json scripts:

{
  "scripts": {
    "generate-schema": "cmd-ipc generate-schema --host http://localhost:8787 --output src/generated/api.ts"
  }
}

Commands

generate-schema

Fetches command definitions from a remote CommandRegistry and generates a TypeScript schema file.

cmd-ipc generate-schema [options]

Options

Option	Required	Description
--host	Yes	Host URL without trailing slash (e.g., https://api.example.com)
--output	Yes	Output path for generated TypeScript file
--prefix	No	Prefix to add to all command IDs

Examples

Basic usage:

cmd-ipc generate-schema \
  --host http://localhost:8787 \
  --output src/generated/api-schema.ts

With prefix:

cmd-ipc generate-schema \
  --host https://api.example.com \
  --output src/generated/cloud-schema.ts \
  --prefix cloud

How It Works

1. Fetch Schema: The CLI fetches the command list from the server’s /cmds.json endpoint
2. Parse Response: It receives the list of commands with their schemas
3. Convert Schemas: JSON Schema definitions are converted to Valibot schemas
4. Generate TypeScript: A .ts file is written with full type definitions

Generated File Structure

The generated file exports a schema named based on the --prefix option:

• No prefix: RemoteCommandSchema
• With prefix: ${PascalCasePrefix}CommandSchema (e.g., --prefix cloud → CloudCommandSchema, --prefix my-api → MyApiCommandSchema)

// Auto-generated by cmd-ipc CLI - DO NOT EDIT
// Generated from: http://localhost:8787
// Generated at: 2024-01-15T10:30:00.000Z

import * as v from 'valibot'

import type { CommandSchemaMap } from '@coralstack/cmd-ipc'

export const RemoteCommandSchema = {
  'user.create': {
    description: 'Creates a new user account',
    request: v.object({
      name: v.string(),
      email: v.pipe(v.string(), v.email()),
    }),
    response: v.object({
      id: v.string(),
      name: v.string(),
      email: v.string(),
    }),
  },
  'user.delete': {
    description: 'Deletes a user by ID',
    request: v.object({
      id: v.string(),
    }),
    response: v.object({
      success: v.boolean(),
    }),
  },
} as const satisfies CommandSchemaMap