|
| 1 | +--- |
| 2 | +title: flags |
| 3 | +--- |
| 4 | + |
| 5 | +# Flags |
| 6 | + |
| 7 | +Flags are used to provide additional configuration and parameters for commands. Clerc supports various types of options, including built-in JavaScript types such as Boolean, String, Number, and also custom types. |
| 8 | + |
| 9 | +_Clerc_'s flag parsing is powered by [`@clerc/parser`](https://github.com/clercjs/clerc/blob/main/packages/parser) and has many features: |
| 10 | + |
| 11 | +- Array and custom types |
| 12 | +- Flag delimiters: `--flag value`, `--flag=value`, `--flag:value` and `--flag.value` |
| 13 | +- Combined aliases: `-abcd 2` → `-a -b -c -d 2` |
| 14 | +- [End-of-file](https://unix.stackexchange.com/a/11382): pass `--` to end parsing |
| 15 | + |
| 16 | +Flags can be specified in the `flags` object property, where the key is the flag name and the value is either an flag type function or an object describing the flag. |
| 17 | + |
| 18 | +It's recommended to use camelCase for flag names as it will be interpreted as parsing the equivalent kebab-case flag. |
| 19 | + |
| 20 | +The flag type function can be any function that accepts a string and returns the parsed value. The default JavaScript constructors should cover most use cases: [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/String), [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/Number), [Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean/Boolean), etc. |
| 21 | + |
| 22 | +The flag description object can be used to store additional information about the flag, such as `alias`, `default`, and `description`. To accept multiple values for a flag, wrap the type function in an array. |
| 23 | + |
| 24 | +All provided information will be used to generate better help documentation. |
| 25 | + |
| 26 | +Example: |
| 27 | + |
| 28 | +```ts |
| 29 | +// $ node ./foo-cli.mjs echo --some-boolean --some-string hello --some-number 1 -n 2 |
| 30 | + |
| 31 | +const cli = Clerc.create() |
| 32 | + .scriptName("foo-cli") |
| 33 | + .description("A simple CLI") |
| 34 | + .version("1.0.0") |
| 35 | + .command("echo", "Echo", { |
| 36 | + flags: { |
| 37 | + someBoolean: { |
| 38 | + type: Boolean, |
| 39 | + description: "Some boolean flag", |
| 40 | + }, |
| 41 | + |
| 42 | + someString: { |
| 43 | + type: String, |
| 44 | + description: "Some string flag", |
| 45 | + default: "n/a", |
| 46 | + }, |
| 47 | + |
| 48 | + someNumber: { |
| 49 | + // Wrap the type function in an array to allow multiple values |
| 50 | + type: [Number], |
| 51 | + alias: "n", |
| 52 | + description: "Array of numbers. (e.g. -n 1 -n 2 -n 3)", |
| 53 | + }, |
| 54 | + |
| 55 | + object: { |
| 56 | + type: Object, |
| 57 | + description: "An object flag. (e.g. --object.key value)", |
| 58 | + }, |
| 59 | + |
| 60 | + counter: { |
| 61 | + type: [Boolean], |
| 62 | + description: "A counter flag. (e.g. -c -c -c)", |
| 63 | + }, |
| 64 | + }, |
| 65 | + }) |
| 66 | + .on("echo", (ctx) => { |
| 67 | + ctx.flags; |
| 68 | + // ^? |
| 69 | + ctx.flags.someBoolean; // => true |
| 70 | + ctx.flags.someString; // => "hello" |
| 71 | + ctx.flags.someNumber; // => [1, 2] |
| 72 | + ctx.flags.object; // => { key: "value" } |
| 73 | + ctx.flags.counter; // => 2 |
| 74 | + }) |
| 75 | + .parse(); |
| 76 | +``` |
| 77 | + |
| 78 | +## Built-in Advanced Types |
| 79 | + |
| 80 | +Clerc provides some built-in advanced flag types to facilitate common needs: |
| 81 | + |
| 82 | +- `Choices`: Restrict flag values to a predefined set. |
| 83 | + |
| 84 | +```ts |
| 85 | +import { Choices } from "clerc"; |
| 86 | + |
| 87 | +Clerc.create() |
| 88 | + .command("serve", "Start the server", { |
| 89 | + flags: { |
| 90 | + mode: { |
| 91 | + type: Choices("development", "production", "test"), |
| 92 | + default: "development" as const, |
| 93 | + description: "Set the application mode", |
| 94 | + }, |
| 95 | + }, |
| 96 | + }) |
| 97 | + .on("serve", (ctx) => { |
| 98 | + ctx.flags.mode; |
| 99 | + // ^? |
| 100 | + }) |
| 101 | + .parse(); |
| 102 | +``` |
| 103 | + |
| 104 | +## Custom Flag Types |
| 105 | + |
| 106 | +You can create custom flag types by providing a custom type function. The type function accepts a string argument and returns the parsed value. |
| 107 | + |
| 108 | +```ts |
| 109 | +// Custom type function that parses a comma-separated string into an array of strings |
| 110 | +const CommaSeparatedList = (value: string): string[] => |
| 111 | + value.split(",").map((item) => item.trim()); |
| 112 | + |
| 113 | +const cli = Clerc.create() |
| 114 | + .scriptName("custom-cli") |
| 115 | + .description("A CLI using a custom flag type") |
| 116 | + .version("1.0.0") |
| 117 | + .command("list", "Display list", { |
| 118 | + flags: { |
| 119 | + items: { |
| 120 | + type: CommaSeparatedList, |
| 121 | + default: [] as string[], |
| 122 | + description: "Comma-separated list of strings", |
| 123 | + }, |
| 124 | + }, |
| 125 | + }) |
| 126 | + .on("list", (ctx) => { |
| 127 | + console.log("Items:", ctx.flags.items); |
| 128 | + // ^? |
| 129 | + }) |
| 130 | + .parse(); |
| 131 | +``` |
0 commit comments