# Option

**Kind:** Class

**Source:** [`lib/option.js`](https://github.com/tj/commander.js/blob/main/lib/option.js#L3)

`Option` defines a command-line option, including its flags, default value, environment variable mapping, validation rules, and parsing behavior. It is added to a command and supplies metadata used while parsing arguments and building help output.

## Methods

| Method | Signature | Returns |
|---|---|---|
| `default` | `default(value: undefined, description: undefined)` | `void` |
| `preset` | `preset(arg: undefined)` | `void` |
| `conflicts` | `conflicts(names: undefined)` | `void` |
| `implies` | `implies(impliedOptionValues: undefined)` | `void` |
| `env` | `env(name: undefined)` | `void` |
| `argParser` | `argParser(fn: undefined)` | `void` |
| `makeOptionMandatory` | `makeOptionMandatory(mandatory: undefined)` | `void` |
| `hideHelp` | `hideHelp(hide: undefined)` | `void` |
| `_collectValue` | `_collectValue(value: undefined, previous: undefined)` | `void` |
| `choices` | `choices(values: undefined)` | `void` |
| `name` | `name()` | `void` |
| `attributeName` | `attributeName()` | `void` |
| `helpGroup` | `helpGroup(heading: undefined)` | `void` |
| `is` | `is(arg: undefined)` | `void` |
| `isBoolean` | `isBoolean()` | `void` |

## Where it refuses work

- `Option` stops the work with `InvalidArgumentError` when `!this.argChoices.includes(arg)`.
- `Option` stops the work with an early return when `previous === this.defaultValue || !Array.isArray(previous)`.
- `Option` stops the work with an early return when `this.variadic`.
- `Option` stops the work with an early return when `this.long`.
- `Option` stops the work with an early return when `this.negate`.

## Diagram

```mermaid
graph LR
  Command[Command] -->|addOption| Option[Option]
  Environment[Environment variable] -->|env| Option
  Option -->|flags, defaults, rules| Parser[Argument parser]
  Parser -->|stores parsed value| CommandOptions[command.opts()]
```

## Usage

```js
const { Command, Option } = require('commander');

const program = new Command();

const formatOption = new Option(
  '-f, --format <type>',
  'select output format'
)
  .choices(['text', 'json'])
  .default('text')
  .env('OUTPUT_FORMAT');

const quietOption = new Option('-q, --quiet', 'suppress output')
  .conflicts('verbose');

program
  .addOption(formatOption)
  .addOption(quietOption);

program.parse();

const options = program.opts();
console.log(options.format);
```

## AI Coding Instructions

- Create options with `new Option(flags, description)` before adding them to a `Command`.
- Use `choices()` for accepted argument values and `argParser()` when values need custom conversion.
- Use `conflicts()` and `implies()` to describe relationships between option names, not flag strings.
- Set `env()` when an option may read its value from an environment variable.
- Use `hideHelp()` only for options that should still parse but should not appear in generated help.

## How it works

I’ll inspect the option-token parsing branch to document the actual preconditions for required, optional, variadic, boolean, and negated flags.

## Relationships

- IMPORTS → `InvalidArgumentError`

## Used by

2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.

### Imported by (2)

- `program` — `index.js`:7
- `Command` — `lib/command.js`:14