argzod !NPM Version !Bundle Size

Minimalistic typescript-first CLI parser 📚

🔍 Overview

argzod is a lightweight CLI argument parsing library that simplifies input validation using Zod. It provides a streamlined alternative to tools like Commander and Yargs, offering seamless Zod integration for robust input validation.

With powerful type inference, argzod ensures type safety without extra configuration, eliminating inconsistencies and making CLI development more intuitive.

🚀 Why Choose argzod?
- ✅ Minimal & Intuitive – A simpler alternative to complex CLI parsers.
- ⚡ Seamless Zod Integration – Validate and transform CLI inputs effortlessly.
- 🔧 Strong Type Inference – No more manual type definitions which can lead to inconsistencies.
Perfect for developers who want a lightweight, type-safe, and modern approach to CLI argument parsing! 🚀

📦 Installation

Install argzod with package manager of your choice

$3

npm install argzod

$3

yarn add argzod

$3

pnpm add argzod

$3

deno install npm:argzod

💻 Quick Start

Let's create a simple app with an unnamed command that has one option, and one argument. For this example, we’ll use Deno for easy running of TypeScript files.

``ts
import { argzod } from "npm:argzod";
import { z } from "npm:zod";

const program = argzod.createProgram({
name: 'my-tool',
});

program.command({
action: ({ options }) => {
console.log(Formats ${options.format.join(', ')} where picked);
},
options: {
format: {
name: ['format', 'f'],
parse: 'many',
schema: z.array(z.enum(['esm', 'cjs', 'iife'])).min(1).max(3)
}
},
args: [
{ schema: z.coerce.number().refine(arg => arg % 2 === 0) }
]
})

program.run();
`

Let's run our program with different sets of options and arguments
`sh
$ deno --allow-all main.ts 42 --format iife cjs

Formats iife, cjs where picked

$ deno --allow-all main.ts 99 --format iife umd

[⚠ Error] | --format | Invalid enum value. Expected 'esm' | 'cjs' | 'iife', received 'umd'

`

📖 API Reference

$3

`ts
createProgram(config: ProgramConfig): Program
`
Creates and returns a new instance of a Program

Example usage:
`ts
import { argzod } from 'argzod';

const program = argzod.createProgram({
name: 'my-tool',
description: 'My skibidi CLI tool',
// If unknown options are met program will still be executed with warn logs
undefinedOptionsBehavior: 'warn',
messages: {
"option-not-defined": "You custom message here",
"zod-parse": (error) => Validation error: ${error.message}
},
onError: ({ error, warn, ignore }) => {
console.log('This is called when program catches error')
},
});
`

$3

`ts
createCommand(def: CommandDefinition & { program: Progam }): Command
``
Creates and returns a Command instance that can be attached to a program.
Command action infers types of options and arguments you have defined. In example below args and options have following types:
`ts
{
args: ["save" | "draft", number],
options: { title: string }
}
`
Example usage:
`ts
// index.ts
import { argzod } from 'argzod';
import { addCommand } from './commands/add';

const program = argzod.createProgram({
name: 'my-tool',
messages: {},
});

program.attachCommand(addCommand);

// commands/add.ts
import { argzod } from 'argzod';
import { program } from '../index';

export const addCommand = argzod.createCommand({
program,
name: 'add',
description: 'adds something',
action: ({ args, options, parsedEntries, unknownOptions }) => {
console.log('===== Adding item =====');

console.log('Count', args[0]);
console.log('Title', options.title);
},
options: {
title: {
name: ['title', 't'],
parse: 'single',
schema: z.string().optional().default('Default title'),
},
},
args: [{ schema: z.enum(['save', 'draft']).catch('draft') }, { schema: z.coerce.number().min(0).max(10).catch(1) }],
});
`

$3

`ts
program.command(def: CommandDefinition): Command
`
Creates a Command and automatically attaches it to a Program instance so it does not need to be attached manually.
See example in createCommand reference section for more information

Example usage:
`ts
const program = argzod.createProgram({
name: 'my-tool',
messages: {},
});

program.command({
name,
options,
args,
action
});
`

$3

`ts
program.attachCommand(Command: Command): Program
`
Attaches given Command to the program. Returns Program so attachCommand calls can be chained.
Example usage:
`ts
import { argzod } from 'argzod';
import { commandA, commandB, commandC } from './commands';

const program = argzod.createProgram(...);

progam
.attachCommand(commandA)
.attachCommand(commandB)
.attachCommand(commandC)
`

$3

`ts
program.run(argv?: string[]): void
`
Parses passed argv and if not provided pocess.argv.
> Commands should be attached before program.run()

Example usage:
`ts
import { argzod } from 'argzod';
import { commandA, commandB, commandC } from './commands';

const program = argzod.createProgram(...);
progam
.attachCommand(commandA)
.attachCommand(commandB)
.attachCommand(commandC)

program.run() // takes arguments from process.argv
// or
program.run(["command or argument", '--option=value', "--other-option", "value1", "value2"]) // pass custom arguments
`

$3

Instance of a program. Can be created with createProgram

Methods
- run Parses arguments and calls action callbacks of attached commands
- command Creates and attaches command to a program
- attachCommand Attaches command to a program

$3

- name: string Name of your tool. Used for help messages
- description?: string Description of your tool. Used for help messages
- messages?: MessageMap An object containing custom error messages. Keys represent error codes and value can either be a string or a function which gives useful information about the error
- undefinedOptionsBehavior?: ErrorLevel Sets error level for unknown options. Default error.
- onError?: (errors: Record) => void Callback function which is called whenever at least one error has been caught.

$3

Instance of a command. Can be created with createCommand or program.command

$3

Fields
- name: string Command alias used to identify command while parsing
- description?: string Command description that will be dispalyed with --help
- options: Record Options which program will try to parse. See OptionDef
- args: ArgumentDefinition[] Arguments which program will try to parse. See ArgumentDefinition
- action A callback function that runs when command is parsed successfuly
`ts
action: (
data: {
args: TArgs,
options: TOpts,
parsedEntries: ParsedEntry[];
unknownOptions: ParsedOption[];
}
) => void
`
Callback function which gets called if options and args are successfuly parsed. Infers from OptionDef and ArgumentDefinition

$3

- name: string | string[] Option aliases for program to check
- description?: string Option description that will appear in --help
- parse: 'boolean' | 'signle' | 'many'
Sets how option values will be parsed
- boolean Expects that option to appear in argv only once and not have any values
- single Expects that option to appear in argv only once and have one value.
- many Expects that option to appear in argv only any amount of times and have any amount of values
- schema?: ZodType Zod type that

#### BooleanOptionDef
The same as OptionDef

#### SingleOptionDef
The same as OptionDef

#### ManyOptionDef
Extends OptionDef
- maxLength?: number A maximum number of values that will be parsed if values are passed space separated (--many-option val1 val2 val3)

$3

- schema: ZodType Zod schema which will be applied to the argument
- description?: string Argument description that will appear in --help (not yet implemented)

$3

Extends JS Error class.
- code: ErrorCode
- level: ErrorLevel
- message: string`