universal-command

# @supernal/universal-command

**Define once, deploy everywhere.** Single source of truth for CLI, API, and MCP interfaces.

## ⚠️ CRITICAL: Use This, Don't Rebuild

If you're building commands for Supernal, **use this package**. Don't create separate CLI/API/MCP implementations.

## Installation

```bash
npm install @supernal/universal-command
```

## Quick Start

### Define a Command

```typescript
import { UniversalCommand } from '@supernal/universal-command';

export const userCreate = new UniversalCommand({
  name: 'user create',
  description: 'Create a new user',
  
  input: {
    parameters: [
      { name: 'name', type: 'string', required: true },
      { name: 'email', type: 'string', required: true },
      { name: 'role', type: 'string', default: 'user', enum: ['user', 'admin'] },
    ],
  },
  
  output: { type: 'json' },
  
  handler: async (args, context) => {
    return await createUser(args);
  },
});
```

### Deploy Everywhere

```typescript
// CLI
program.addCommand(userCreate.toCLI());
// → mycli user create --name "Alice" --email "alice@example.com"

// Next.js API
export const POST = userCreate.toNextAPI();
// → POST /api/users/create

// MCP Tool
const mcpTool = userCreate.toMCP();
// → user_create tool for AI agents
```

## Core Concepts

### Single Handler

Write your logic once. The handler receives validated args and returns the result:

```typescript
handler: async (args, context) => {
  // This same code runs for CLI, API, and MCP
  return await doThing(args);
}
```

### Input Schema

Define parameters once — validation, CLI options, API params, and MCP schema are auto-generated:

```typescript
input: {
  parameters: [
    { name: 'id', type: 'string', required: true },
    { name: 'status', type: 'string', enum: ['draft', 'active', 'done'] },
    { name: 'limit', type: 'number', min: 1, max: 100, default: 10 },
  ],
}
```

### Interface-Specific Options

Override behavior per interface when needed:

```typescript
cli: {
  format: (data)...