A CLI parser built with Zod.
npm install zodcliA CLI parser built with Zod.
```
npm install --save zodcli zod
`ts
import { z } from "zod";
import { argumentParser } from "zodcli";
argumentParser({ options: z.object({ foo: z.string() }).strict() }).parse([
"--foo=bar",
]);
`
You can get CLI arguments passed to the script by using process.argv.slice(2):
`ts
// ./cli.js
import { z } from "zod";
import { argumentParser } from "./dist/index.js";
console.log(
argumentParser({ options: z.object({ foo: z.string() }).strict() }).parse(
process.argv.slice(2)
)
);
// $ node cli.js --foo=bar
// { foo: 'bar' }
`
argumentParser is a function which takes an object with the following properties: options and aliases.
#### options
options is a required property and must have a value of a strict Zod object (z.object({}).strict()). This ensures that any unrecognized arguments are rejected.
- All properties must be in 'camelCase' and be exclusively composed of a-z characters. For example:
- Valid:
- foocatDog
- Foo
- Invalid:
- cat_dog
- 5
- a5
-
When parsed, '--kebab-case' arguments are converted to their respective 'camelCase' properties.
For example:
`ts
import { z } from "zod";
import { argumentParser } from "zodcli";
const options = z
.object({
foo: z.string(),
catDog: z.string(),
})
.strict();
const result = argumentParser({
options,
}).parse(["--foo=bar", "--cat-dog=fish"]);
console.log(result);
// { foo: 'bar', catDog: 'fish' }
`
- All values must be one of the following Zod types:
- z.literal()
- z.string()
- z.number()
- z.null()
And these values can be modified/wrapped with any of the following:
- .transform()
- .optional()
- .default()
- z.union()
- z.array()
#### aliases
aliases is an optional property which allows you to configure argument aliases for options. It is an object where: the properties are lowercase and composed of exclusively a-z charaters; and the values are 'camelCase' strings and appear as properties in the options object.
Parsing requires an explict = between the argument name and its value. For example:
- Valid:
- --foo=bar --cat-dog=fish--foo bar --cat-dog fish
- Invalid:
-
If an argument value is omitted, it will be set as null. You can use this to accept implicit booleans (boolean arguments whose presence implies true) by using a z.union(). For example:
`ts
import { z } from "zod";
import { argumentParser } from "zodcli";
const options = z
.object({
foo: z
.union([
z.literal("true").transform(() => true),
z.literal("false").transform(() => false),
z.null().transform(() => true),
])
.default("false"),
})
.strict();
const result = argumentParser({
options,
}).parse(["--foo"]);
console.log(result);
// { foo: true }
`
You can make options optional by using the .optional() modifier. For example:
`ts
import { z } from "zod";
import { argumentParser } from "zodcli";
const options = z
.object({
foo: z.string(),
catDog: z.string().optional(),
})
.strict();
const result = argumentParser({
options,
}).parse(["--foo=bar"]);
console.log(result);
// { foo: 'bar' }
`
Or, to make all options optional, you can use .partial() on the object. For example:
`ts
import { z } from "zod";
import { argumentParser } from "zodcli";
const options = z
.object({
foo: z.string(),
catDog: z.string(),
})
.partial()
.strict();
const result = argumentParser({
options,
}).parse(["--foo=bar"]);
console.log(result);
// { foo: 'bar' }
`
Note, however, that for booleans, you will likely want to keep them required and simply provide a .default() false value. For example:
`ts
import { z } from "zod";
import { argumentParser } from "zodcli";
const options = z
.object({
foo: z
.union([
z.literal("true").transform(() => true),
z.literal("false").transform(() => false),
z.null().transform(() => true),
])
.default("false"),
catDog: z.string(),
})
.partial()
.required({ foo: true })
.strict();
const result = argumentParser({
options,
}).parse([]);
console.log(result);
// { foo: false }
`
You can coerce non-string values using Zod. For example:
`ts
import { z } from "zod";
import { argumentParser } from "zodcli";
const options = z
.object({
foo: z.coerce.number(),
})
.strict();
const result = argumentParser({
options,
}).parse(["--foo=2.2"]);
console.log(result);
// { foo: 2.2 }
``
- [ ] Help message
- [ ] Commands support
- [ ] Positionals support
- [ ] Object support
- [x] Strict typing of aliases
- [ ] Improve optionality/booleans