Installation

cmd-ipc ships as both a TypeScript package and a Rust crate. Both speak the same wire protocol.

Requirements

TypeScript

• Node.js 20.18.2 or higher
• TypeScript 5.0 or higher (recommended)

Rust

• Rust 1.75 or higher (edition 2021)
• An async executor of your choice (tokio, async-std, smol, futures::executor, etc.) — the crate is runtime-agnostic

Package Installation

TypeScript

npm

npm install @coralstack/cmd-ipc valibot

yarn

yarn add @coralstack/cmd-ipc valibot

pnpm

pnpm add @coralstack/cmd-ipc valibot

bun

bun add @coralstack/cmd-ipc valibot

Note

Valibot is a peer dependency used for schema definition and validation. It’s a lightweight alternative to Zod with excellent tree-shaking support. Unlike Zod, Valibot doesn’t use eval or new Function(), making it compatible with strict Content Security Policy (CSP) environments and runtimes like Cloudflare Workers where these are restricted.

Rust

cargo add coralstack-cmd-ipc

Or in Cargo.toml:

[dependencies]
coralstack-cmd-ipc = "0.1"
schemars = "1"
serde = { version = "1", features = ["derive"] }
serde_json = "1"

The core crate re-exports the #[command] / #[command_service] attribute macros from coralstack-cmd-ipc-macros, so you don’t need to depend on the macros crate directly.

Note

schemars generates JSON Schema from your Rust request types — the same schema the TypeScript implementation advertises via Valibot. This keeps the wire protocol byte-identical across languages.

MCP adapter (optional)

cargo add coralstack-cmd-ipc-mcp

Adds McpServerChannel for exposing a registry as an MCP server via stdio.

Language Setup

TypeScript

TypeScript Configuration

cmd-ipc uses decorators for the @Command syntax. Enable decorators in your tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Caution

Both experimentalDecorators and emitDecoratorMetadata are required for the @Command decorator to work correctly.

Reflect Metadata

The decorator system requires reflect-metadata. Import it once at your application’s entry point:

// main.ts or index.ts
import 'reflect-metadata'

// Rest of your application
import { CommandRegistry } from '@coralstack/cmd-ipc'

Rust

Prelude

Import the common types in one line:

use coralstack_cmd_ipc::prelude::*;

This brings into scope: command, command_service, ChannelError, Command, CommandChannel, CommandDef, CommandError, CommandRegistry, CommandSchema, Config, DynCommand, InMemoryChannel.

Shorter import path (optional)

If the coralstack_ prefix feels long at use sites, alias it in Cargo.toml:

[dependencies]
cmd-ipc = { package = "coralstack-cmd-ipc", version = "0.1" }

Then use cmd_ipc::prelude::*; works throughout your crate.

CLI Installation (TypeScript only, optional)

cmd-ipc includes a CLI for generating schemas from remote services. It’s included in the main TypeScript package:

# Generate TypeScript schema from a remote HTTP endpoint
npx cmd-ipc generate-schema --url http://localhost:8787 --output ./src/api-schema.ts

Or add it as a script in your package.json:

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

Note

Rust doesn’t yet ship a schema-generation CLI. For now, consume schemas from an HTTP endpoint using the TypeScript CLI and translate by hand, or let the registry’s runtime command discovery populate remote command metadata directly.

Package Exports

TypeScript

// Main exports - CommandRegistry, Channels, Decorators
import {
  CommandRegistry,
  MessagePortChannel,
  HTTPChannel,
  Command,
  registerCommands,
} from '@coralstack/cmd-ipc'

// Testing utilities
import { TestLogger } from '@coralstack/cmd-ipc/testing'

Rust

// Prelude — most common types
use coralstack_cmd_ipc::prelude::*;

// Or import by path
use coralstack_cmd_ipc::{
    CommandRegistry, Config, CommandChannel, InMemoryChannel,
    Command, CommandError, command, commands,
};

// MCP adapter (separate crate)
use coralstack_cmd_ipc_mcp::McpServerChannel;