feat: add automatic --no-<flag> support for boolean options

All boolean options now automatically support a negated form to explicitly
set the option to false:

  --verbose      → { verbose: true }
  --no-verbose   → { verbose: false }
  (neither)      → { verbose: default or undefined }

If both --flag and --no-flag are specified, throws a HelpError with a
clear message about the conflict.

In help output, booleans with default: true display as --no-<flag>
since that's how users would turn them off. Short aliases are not shown
for negated forms.

Includes:
- Parser support for processing --no-* flags
- Help text updates for default:true booleans
- Comprehensive tests for both parser and help
- README documentation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: boneskull

README.md

@@ -336,6 +336,32 @@ opt.count(); // -vvv → 3
 | `hidden`      | `boolean`  | Hide from `--help` output                        |
 | `required`    | `boolean`  | Mark as required (makes the option non-nullable) |
 
+### Boolean Negation (`--no-<flag>`)
+
+All boolean options automatically support a negated form `--no-<flag>` to explicitly set the option to `false`:
+
+```shell
+$ my-cli --verbose      # verbose: true
+$ my-cli --no-verbose   # verbose: false
+$ my-cli                # verbose: undefined (or default)
+```
+
+If both `--flag` and `--no-flag` are specified, bargs throws an error:
+
+```shell
+$ my-cli --verbose --no-verbose
+Error: Conflicting options: --verbose and --no-verbose cannot both be specified
+```
+
+In help output, booleans with `default: true` display as `--no-<flag>` (since that's how users would turn them off):
+
+```typescript
+opt.options({
+  colors: opt.boolean({ default: true, description: 'Use colors' }),
+});
+// Help output shows: --no-colors  Use colors  [boolean] default: true
+```
+
 ### `opt.options(schema)`
 
 Create a parser from an options schema:

src/help.ts

@@ -172,6 +172,9 @@ const getTypeLabel = (def: OptionDef): string => {
 
 /**
  * Format a single option for help output.
+ *
+ * For boolean options with `default: true`, shows `--no-<name>` instead of
+ * `--<name>` since that's how users would turn it off.
  */
 const formatOptionHelp = (
   name: string,
@@ -180,9 +183,18 @@ const formatOptionHelp = (
 ): string => {
   const parts: string[] = [];
 
-  // Build flag string: -v, --verbose
+  // For boolean options with default: true, show --no-<name>
+  // since that's how users would turn it off
+  const displayName =
+    def.type === 'boolean' && def.default === true ? `no-${name}` : name;
+
+  // Build flag string: -v, --verbose (or --no-verbose for default:true booleans)
   const shortAlias = def.aliases?.find((a) => a.length === 1);
-  const flagText = shortAlias ? `-${shortAlias}, --${name}` : `    --${name}`;
+  // Don't show short alias for negated booleans
+  const flagText =
+    shortAlias && displayName === name
+      ? `-${shortAlias}, --${displayName}`
+      : `    --${displayName}`;
   parts.push(`  ${styler.flag(flagText)}`);
 
   // Pad to align descriptions

src/parser.ts

@@ -20,8 +20,13 @@ import type {
   PositionalsSchema,
 } from './types.js';
 
+import { HelpError } from './errors.js';
+
 /**
  * Build parseArgs options config from our options schema.
+ *
+ * For boolean options, also adds `no-<name>` variants to support explicit
+ * negation (e.g., `--no-verbose` sets `verbose` to `false`).
  */
 const buildParseArgsConfig = (
   schema: OptionsSchema,
@@ -55,6 +60,11 @@ const buildParseArgsConfig = (
     }
 
     config[name] = opt;
+
+    // For boolean options, add negated form (--no-<name>)
+    if (def.type === 'boolean') {
+      config[`no-${name}`] = { type: 'boolean' };
+    }
   }
 
   return config;
@@ -183,6 +193,45 @@ const coercePositionals = (
   return result;
 };
 
+/**
+ * Process negated boolean options (--no-<name>).
+ *
+ * - If `--no-<name>` is true and `--<name>` is not set, sets `<name>` to false
+ * - If both `--<name>` and `--no-<name>` are set, throws an error
+ * - Removes all `no-<name>` keys from the result
+ */
+const processNegatedBooleans = (
+  values: Record<string, unknown>,
+  schema: OptionsSchema,
+): Record<string, unknown> => {
+  const result = { ...values };
+
+  for (const [name, def] of Object.entries(schema)) {
+    if (def.type !== 'boolean') {
+      continue;
+    }
+
+    const negatedKey = `no-${name}`;
+    const hasPositive = result[name] === true;
+    const hasNegative = result[negatedKey] === true;
+
+    if (hasPositive && hasNegative) {
+      throw new HelpError(
+        `Conflicting options: --${name} and --${negatedKey} cannot both be specified`,
+      );
+    }
+
+    if (hasNegative && !hasPositive) {
+      result[name] = false;
+    }
+
+    // Always remove the negated key from result
+    delete result[negatedKey];
+  }
+
+  return result;
+};
+
 /**
  * Options for parseSimple.
  */
@@ -221,8 +270,14 @@ export const parseSimple = <
     strict: true,
   });
 
+  // Process negated boolean options (--no-<flag>)
+  const processedValues = processNegatedBooleans(
+    values as Record<string, unknown>,
+    optionsSchema,
+  );
+
   // Coerce and apply defaults
-  const coercedValues = coerceValues(values, optionsSchema);
+  const coercedValues = coerceValues(processedValues, optionsSchema);
   const coercedPositionals = coercePositionals(positionals, positionalsSchema);
 
   return {

test/help.test.ts

@@ -130,6 +130,92 @@ describe('generateHelp', () => {
     expect(help, 'to contain', 'LOGGING');
     expect(help, 'to contain', 'NETWORK');
   });
+
+  describe('boolean negation display', () => {
+    it('shows --no-<flag> for boolean with default: true', () => {
+      const help = stripAnsi(
+        generateHelp({
+          name: 'my-cli',
+          options: {
+            verbose: opt.boolean({
+              default: true,
+              description: 'Enable verbose output',
+            }),
+          },
+        }),
+      );
+
+      expect(help, 'to contain', '--no-verbose');
+      expect(help, 'not to match', /\s--verbose\s/); // should not show --verbose without "no-"
+    });
+
+    it('shows --<flag> for boolean with default: false', () => {
+      const help = stripAnsi(
+        generateHelp({
+          name: 'my-cli',
+          options: {
+            verbose: opt.boolean({
+              default: false,
+              description: 'Enable verbose output',
+            }),
+          },
+        }),
+      );
+
+      expect(help, 'to contain', '--verbose');
+      expect(help, 'not to contain', '--no-verbose');
+    });
+
+    it('shows --<flag> for boolean without default', () => {
+      const help = stripAnsi(
+        generateHelp({
+          name: 'my-cli',
+          options: {
+            verbose: opt.boolean({ description: 'Enable verbose output' }),
+          },
+        }),
+      );
+
+      expect(help, 'to contain', '--verbose');
+      expect(help, 'not to contain', '--no-verbose');
+    });
+
+    it('does not show short alias for negated boolean', () => {
+      const help = stripAnsi(
+        generateHelp({
+          name: 'my-cli',
+          options: {
+            verbose: opt.boolean({
+              aliases: ['v'],
+              default: true,
+              description: 'Enable verbose output',
+            }),
+          },
+        }),
+      );
+
+      // Should show --no-verbose but NOT -v for the negated form
+      expect(help, 'to contain', '--no-verbose');
+      expect(help, 'not to match', /-v,\s*--no-verbose/);
+    });
+
+    it('shows short alias for non-negated boolean', () => {
+      const help = stripAnsi(
+        generateHelp({
+          name: 'my-cli',
+          options: {
+            verbose: opt.boolean({
+              aliases: ['v'],
+              default: false,
+              description: 'Enable verbose output',
+            }),
+          },
+        }),
+      );
+
+      expect(help, 'to match', /-v,\s*--verbose/);
+    });
+  });
 });
 
 describe('generateHelp positionals', () => {

test/parser.test.ts

@@ -4,6 +4,7 @@
 import { expect } from 'bupkis';
 import { describe, it } from 'node:test';
 
+import { HelpError } from '../src/errors.js';
 import { opt } from '../src/opt.js';
 import { parseSimple } from '../src/parser.js';
 import { validatePositionalsSchema } from '../src/validate.js';
@@ -31,6 +32,120 @@ describe('parseSimple', () => {
     expect(result.values, 'to deeply equal', { verbose: true });
   });
 
+  describe('boolean negation (--no-<flag>)', () => {
+    it('sets flag to false with --no-<flag>', () => {
+      const result = parseSimple({
+        args: ['--no-verbose'],
+        options: {
+          verbose: opt.boolean(),
+        },
+      });
+
+      expect(result.values, 'to deeply equal', { verbose: false });
+    });
+
+    it('--no-<flag> overrides default: true', () => {
+      const result = parseSimple({
+        args: ['--no-verbose'],
+        options: {
+          verbose: opt.boolean({ default: true }),
+        },
+      });
+
+      expect(result.values, 'to deeply equal', { verbose: false });
+    });
+
+    it('--<flag> sets flag to true', () => {
+      const result = parseSimple({
+        args: ['--verbose'],
+        options: {
+          verbose: opt.boolean(),
+        },
+      });
+
+      expect(result.values, 'to deeply equal', { verbose: true });
+    });
+
+    it('throws HelpError when both --<flag> and --no-<flag> are specified', () => {
+      expect(
+        () =>
+          parseSimple({
+            args: ['--verbose', '--no-verbose'],
+            options: {
+              verbose: opt.boolean(),
+            },
+          }),
+        'to throw a',
+        HelpError,
+      );
+    });
+
+    it('error message mentions conflicting options', () => {
+      expect(
+        () =>
+          parseSimple({
+            args: ['--no-verbose', '--verbose'],
+            options: {
+              verbose: opt.boolean(),
+            },
+          }),
+        'to throw',
+        /Conflicting options.*--verbose.*--no-verbose/,
+      );
+    });
+
+    it('negated keys never appear in result values', () => {
+      const result = parseSimple({
+        args: ['--no-verbose'],
+        options: {
+          verbose: opt.boolean(),
+        },
+      });
+
+      expect(Object.keys(result.values), 'not to contain', 'no-verbose');
+      expect(result.values, 'to have keys', ['verbose']);
+    });
+
+    it('works with multiple boolean options', () => {
+      const result = parseSimple({
+        args: ['--verbose', '--no-quiet', '--no-debug'],
+        options: {
+          debug: opt.boolean({ default: true }),
+          quiet: opt.boolean(),
+          verbose: opt.boolean(),
+        },
+      });
+
+      expect(result.values, 'to deeply equal', {
+        debug: false,
+        quiet: false,
+        verbose: true,
+      });
+    });
+
+    it('applies default when neither flag nor negation provided', () => {
+      const result = parseSimple({
+        args: [],
+        options: {
+          verbose: opt.boolean({ default: true }),
+        },
+      });
+
+      expect(result.values, 'to deeply equal', { verbose: true });
+    });
+
+    it('returns undefined when no flag, no negation, and no default', () => {
+      const result = parseSimple({
+        args: [],
+        options: {
+          verbose: opt.boolean(),
+        },
+      });
+
+      expect(result.values.verbose, 'to be', undefined);
+    });
+  });
+
   it('parses number options', () => {
     const result = parseSimple({
       args: ['--count', '5'],