@robingenz/zli

@robingenz/zli

A powerful CLI parser built with TypeScript and Zod for type-safe command-line interfaces.

Features

• 🛡️ Type-safe: Built with TypeScript and Zod for runtime validation.
• 📋 Declarative: Define commands, options, and arguments with simple schemas.
• 🔄 Flexible parsing: Support for long flags, short flags, and flag clustering.
• 🔀 Smart conversion: Automatic kebab-case to camelCase conversion.
• 🏷️ Alias support: Define short aliases for any option.
• 📦 Array handling: Automatic normalization of single values to arrays.

• 🎯 Default commands: Set a default command to run when no command is specified.
• ❓ Help message: Automatic help generation for commands and options.
• ⚠️ Error handling: Clear, actionable error messages.
• 🚀 Zero dependencies: Only requires Zod as a peer dependency.
• 📦 ESM support: Modern ES modules with full TypeScript support.

Installation

npm install @robingenz/zli zod

Usage

Basic Example

import { z } from 'zod';
import { defineConfig, defineCommand, defineOptions, processConfig } from '@robingenz/zli';

// Define a simple command
const greetCommand = defineCommand({
  description: 'Greet someone',
  options: defineOptions(
    z.object({
      name: z.string().describe('Name to greet'),
      loud: z.boolean().default(false).describe('Use uppercase'),
    }),
    { n: 'name', l: 'loud' } // Short aliases

action: async (options) = { const greeting = Hello, ${options.name}!; console.log(options.loud ? greeting.toUpperCase() : greeting); }, });

// Configure the CLI const config = defineConfig({ meta: { name: 'my-cli', version: '1.0.0', description: 'A simple CLI example', }, commands: { greet: greetCommand, }, defaultCommand: greetCommand, });

// Process command line arguments try { const result = processConfig(config, process.argv.slice(2)); await result.command.action(result.options, result.args); } catch (error) { console.error('Error:', error.message); process.exit(1); }

### Command Usage

Show help

my-cli --help my-cli greet --help

Run commands

my-cli greet --name Alice my-cli greet -n Bob --loud