https://github.com/matteopolak/zod-to-cli
Type-safe CLI argument parsing using Zod schemas.
https://github.com/matteopolak/zod-to-cli
args cli command-line parser zod
Last synced: about 8 hours ago
JSON representation
Type-safe CLI argument parsing using Zod schemas.
- Host: GitHub
- URL: https://github.com/matteopolak/zod-to-cli
- Owner: matteopolak
- Created: 2026-04-15T04:15:35.000Z (12 days ago)
- Default Branch: main
- Last Pushed: 2026-04-15T04:45:43.000Z (12 days ago)
- Last Synced: 2026-04-15T06:27:36.750Z (12 days ago)
- Topics: args, cli, command-line, parser, zod
- Language: TypeScript
- Homepage: https://npmjs.com/package/zod-to-cli
- Size: 41 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# zod to cli
Type-safe CLI argument parsing using Zod schemas.
Define your CLI interface with a Zod schema, get back typed arguments. Supports flags, aliases, arrays, booleans, numbers, and automatic help generation.
## Install
```bash
pnpm add zod-to-cli zod
```
## Quick Example
```typescript
import { z, meta, cli } from 'zod-to-cli';
const schema = z.object({
name: z.string().register(meta, {
description: 'Your name',
aliases: ['n'],
}),
verbose: z
.boolean()
.default(false)
.register(meta, {
description: 'Enable verbose output',
aliases: ['v'],
}),
});
const args = cli(schema, {
name: 'my-cli',
description: 'A simple CLI tool',
version: '1.0.0',
});
// args is fully typed: { name: string, verbose: boolean }
console.log(args.name, args.verbose);
```
Run it:
```bash
$ my-cli --name Alice -v
Alice true
$ my-cli --help
my-cli v1.0.0
A simple CLI tool
USAGE:
my-cli [OPTIONS]
OPTIONS:
-n, --name Your name (required)
-v, --verbose Enable verbose output
-h, --help Show help
--version Show version
```
## Features
- **Type-safe**: Arguments are parsed and validated against your Zod schema
- **Flag aliases**: Short flags like `-n` for `--name`
- **Arrays**: Collect multiple values with `--tag foo --tag bar`
- **Booleans**: Supports negation (`--no-verbose`)
- **Count flags**: `-vvv` for verbosity levels
- **Help generation**: Automatic `--help` and `--version`
- **Validation**: Uses Zod's built-in validation (min/max, email, etc.)
## More Examples
See the `examples/` directory for:
- [basic.ts](examples/basic.ts) - flags and options
- [positional.ts](examples/positional.ts) - positional arguments
- [subcommands.ts](examples/subcommands.ts) - git-style subcommands
## Requirements
- Node.js >= 20.0.0
- Zod ^4.0.0 (peer dependency)
## License
MIT