Universal Command: Define Once, Deploy to CLI, API, and MCP

Every time I start a new project with both a CLI and an API, I end up writing the same command logic twice. Sometimes three times if there's an MCP server involved. The parameter validation is duplicated. The error handling is duplicated. The documentation is duplicated. And inevitably, they drift apart.

Today we're open-sourcing Universal Command, a TypeScript library that lets you define commands once and deploy them to CLI (Commander.js), REST API (Next.js routes), OpenAPI specs, and MCP servers automatically.

The Problem

Consider a simple user management command. In a typical project, you might have:

CLI version (src/cli/users.ts):

program
  .command('create-user')
  .option('--name <name>', 'User name')
  .option('--email <email>', 'User email')
  .option('--role <role>', 'User role', 'member')
  .action(async (options) => {
    // Validation logic
    if (!options.name) throw new Error('Name required');
    if (!options.email) throw new Error('Email required');
    // Business logic
    const user = await createUser(options);
    console.log(`Created user: ${user.id}`);
  });

API version (app/api/users/route.ts):

export async function POST(req: Request) {
  const body = await req.json();
  // Same validation logic, written again
  if (!body.name) return Response.json({ error: 'Name required' }, { status: 400 });
  if (!body.email) return Response.json({ error: 'Email required' }, { status: 400 });
  // Same business logic
  const user = await createUser(body);
  return Response.json(user);
}

MCP version (src/mcp/tools.ts):

server.tool('create_user', {
  name: { type: 'string', description: 'User name' },
  email: { type: 'string', description: 'User email' },
  role: { type: 'string', description: 'User role' }
}, async (params) => {
  // Same validation again
  // Same business logic again
});

Three places to maintain. Three places where bugs can be introduced. Three places that will inevitably drift apart.

The Solution

With Universal Command, you define the command once:

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

export const createUser = new UniversalCommand({
  name: 'create-user',
  description: 'Create a new user account',
  category: 'users',

  parameters: {
    name: {
      type: 'string',
      required: true,
      description: 'User display name'
    },
    email: {
      type: 'string',
      required: true,
      description: 'User email address',
      validate: (v) => v.includes('@') || 'Invalid email format'
    },
    role: {
      type: 'string',
      default: 'member',
      description: 'User role',
      choices: ['admin', 'member', 'guest']
    }
  },

  execute: async ({ name, email, role }) => {
    const user = await db.users.create({ name, email, role });
    return {
      success: true,
      data: user,
      message: `Created user ${user.id}`
    };
  }
});

Then generate all the targets:

import { generateCLI, generateNextRoutes, generateMCPServer } from '@supernal/universal-command/generators';

// Generate Commander.js CLI
generateCLI({ commands: [createUser], outputPath: './src/cli' });

// Generate Next.js API routes
generateNextRoutes({ commands: [createUser], outputPath: './app/api' });

// Generate MCP server
generateMCPServer({ commands: [createUser], outputPath: './src/mcp' });

// Generate OpenAPI spec
generateOpenAPI({ commands: [createUser], outputPath: './docs/api.yaml' });

What You Get

Consistent Validation

The validation logic is defined once and applied everywhere. If email must contain '@', that's enforced in CLI, API, and MCP identically.

Automatic Documentation

The OpenAPI generator creates accurate API documentation from your command definitions. The CLI gets --help output automatically. MCP tools get proper descriptions.

Type Safety

Parameters are fully typed. The execute function receives typed parameters based on your schema definition:

execute: async ({ name, email, role }) => {
  // name: string (required)
  // email: string (required)
  // role: 'admin' | 'member' | 'guest' (with default)
}

Scope-Based Context

For multi-tenant applications, Universal Command supports scope-based execution:

import { ScopeRegistry } from '@supernal/universal-command/scopes';

const scopes = new ScopeRegistry();

// Define a tenant scope
scopes.register('tenant', {
  resolve: async (ctx) => ctx.headers['x-tenant-id'],
  validate: async (tenantId) => db.tenants.exists(tenantId)
});

// Commands automatically receive scope context
const listUsers = new UniversalCommand({
  name: 'list-users',
  scopes: ['tenant'],
  execute: async (params, { scopes }) => {
    const tenantId = scopes.get('tenant');
    return db.users.findByTenant(tenantId);
  }
});

Architecture

The library is structured around a few core concepts:

UniversalCommand: The command definition with parameters, validation, and execution logic.

CommandRegistry: Organizes commands by category and provides lookup/discovery.

Generators: Plugins that transform command definitions into target-specific code (CLI, API routes, MCP tools, OpenAPI specs).

ScopeRegistry: Manages execution context like tenant IDs, user sessions, or feature flags.

┌─────────────────────────────────────────────────────────┐
│                  Command Definitions                      │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐        │
│  │ create  │ │  list   │ │ delete  │ │   ...   │        │
│  │  user   │ │  users  │ │  user   │ │         │        │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘        │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│                   Code Generators                         │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐        │
│  │Commander│ │ Next.js │ │   MCP   │ │ OpenAPI │        │
│  │   CLI   │ │ Routes  │ │ Server  │ │  Spec   │        │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘        │
└─────────────────────────────────────────────────────────┘

Why Not Just Use tRPC?

tRPC is excellent for type-safe API communication between TypeScript clients and servers. But it's focused on the client-server boundary.

Universal Command solves a different problem: you have the same commands that need to be accessible via multiple interfaces. A user should be able to sc user create --name "Alice" from the terminal, POST /api/users from a web app, and use an MCP tool from an AI assistant - all invoking the same underlying logic.

tRPC doesn't generate CLIs. It doesn't generate MCP servers. Universal Command does.

Getting Started

npm install @supernal/universal-command

Define your commands:

// src/commands/index.ts
import { UniversalCommand, CommandRegistry } from '@supernal/universal-command';

export const commands = new CommandRegistry();

commands.register(new UniversalCommand({
  name: 'hello',
  description: 'Say hello',
  parameters: {
    name: { type: 'string', default: 'World' }
  },
  execute: async ({ name }) => ({
    success: true,
    message: `Hello, ${name}!`
  })
}));

Generate your targets:

// scripts/generate.ts
import { commands } from '../src/commands';
import { generateCLI, generateNextRoutes } from '@supernal/universal-command/generators';

generateCLI({
  registry: commands,
  outputPath: './src/cli/generated'
});

generateNextRoutes({
  registry: commands,
  outputPath: './app/api/generated'
});

What's Next

We're using Universal Command internally for our CLI tools and seeing significant reduction in maintenance burden. Features we're exploring:

Runtime adapter: Skip code generation entirely and run commands through a universal runtime
More generators: Fastify, Express, gRPC
Schema-first mode: Define commands in YAML/JSON, generate TypeScript
Versioning: Support multiple versions of commands simultaneously

Open Source

Universal Command is MIT licensed and available at:

GitHub: github.com/supernalintelligence/universal-command

npm: @supernal/universal-command (publishing soon)

We'd love feedback, issues, and contributions. If you're tired of writing the same command logic three times, give it a try.