Minimalistic typescript-first CLI parser powerd with Zod
npm install argzodnpm install argzod
yarn add argzod
pnpm add argzod
deno install npm:argzod
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 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`