feat: add named positionals for help text display

Add optional 'name' property to PositionalBase interface that allows
developers to specify meaningful names for positional arguments in
help text. Without a name, positionals display as <arg0>, <arg1>, etc.

Changes:
- Add name?: string to PositionalBase in types.ts
- Add formatPositionalUsage() and buildPositionalsUsage() helpers
- Update generateHelp() to show positionals in usage line
- Update generateCommandHelp() to show command positionals
- Add 5 new tests for positional name display
- Update examples to use named positionals

Usage: bargs.stringPos({ name: 'source', required: true })
Shows: $ my-cli [options] <source>

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

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

Author: boneskull

examples/greeter.ts

@@ -34,36 +34,36 @@ const optionsDef = bargs.options({
 });
 
 const positionalsDef = bargs.positionals(
-  bargs.stringPos({ description: 'Name to greet', required: true }),
+  bargs.stringPos({
+    description: 'Name to greet',
+    required: true,
+    name: 'name',
+  }),
 );
 
-const main = async () => {
-  const result = await bargs({
-    name: 'greeter',
-    version: '1.0.0',
-    description: 'A friendly greeter CLI',
-    options: optionsDef,
-    positionals: positionalsDef,
-  });
-
-  // Destructure the result
-  const { positionals, values } = result;
-  const [name] = positionals;
-  const { greeting, shout, verbose } = values;
+const result = bargs({
+  name: 'greeter',
+  version: '1.0.0',
+  description: 'A friendly greeter CLI',
+  options: optionsDef,
+  positionals: positionalsDef,
+});
 
-  // Build the message
-  let message = `${greeting}, ${name}!`;
+// Destructure the result
+const { positionals, values } = result;
+const [name] = positionals;
+const { greeting, shout, verbose } = values;
 
-  if (shout) {
-    message = message.toUpperCase();
-  }
+// Build the message
+let message = `${greeting}, ${name}!`;
 
-  // Output
-  if (verbose) {
-    console.log('Configuration:', { greeting, name, shout });
-  }
+if (shout) {
+  message = message.toUpperCase();
+}
 
-  console.log(message);
-};
+// Output
+if (verbose) {
+  console.log('Configuration:', { greeting, name, shout });
+}
 
-void main();
+console.log(message);

examples/tasks.ts

@@ -62,7 +62,11 @@ await bargs({
         }),
       },
       positionals: [
-        bargs.stringPos({ description: 'Task description', required: true }),
+        bargs.stringPos({
+          description: 'Task description',
+          name: 'text',
+          required: true,
+        }),
       ],
       handler: async ({ positionals, values }) => {
         const [text] = positionals;
@@ -126,7 +130,7 @@ await bargs({
     done: bargs.command({
       description: 'Mark a task as complete',
       positionals: [
-        bargs.stringPos({ description: 'Task ID', required: true }),
+        bargs.stringPos({ description: 'Task ID', name: 'id', required: true }),
       ],
       handler: async ({ positionals, values }) => {
         const [idStr] = positionals;

src/help.ts

@@ -5,11 +5,38 @@ import type {
   CommandConfigInput,
   OptionDef,
   OptionsSchema,
+  PositionalDef,
   PositionalsSchema,
 } from './types.js';
 
 import { bold, cyan, dim, yellow } from './ansi.js';
 
+/**
+ * Format a single positional for help usage line. Required positionals use
+ * <name>, optional use [name]. Variadic positionals append "...".
+ */
+const formatPositionalUsage = (def: PositionalDef, index: number): string => {
+  const name = def.name ?? `arg${index}`;
+  const isRequired = def.required || 'default' in def;
+  const isVariadic = def.type === 'variadic';
+  const displayName = isVariadic ? `${name}...` : name;
+
+  return isRequired ? `<${displayName}>` : `[${displayName}]`;
+};
+
+/**
+ * Build the positionals usage string from a schema.
+ */
+const buildPositionalsUsage = (schema?: PositionalsSchema): string => {
+  if (!schema || schema.length === 0) {
+    return '';
+  }
+
+  return schema
+    .map((def, index) => formatPositionalUsage(def, index))
+    .join(' ');
+};
+
 /**
  * Get type label for help display.
  */
@@ -100,7 +127,11 @@ export const generateHelp = <
   if (hasCommands(config)) {
     lines.push(`  $ ${config.name} <command> [options]`);
   } else {
-    lines.push(`  $ ${config.name} [options]`);
+    const positionalsPart = buildPositionalsUsage(config.positionals);
+    const usageParts = [`$ ${config.name}`, '[options]', positionalsPart]
+      .filter(Boolean)
+      .join(' ');
+    lines.push(`  ${usageParts}`);
   }
   lines.push('');
 
@@ -194,7 +225,15 @@ export const generateCommandHelp = <
 
   // Usage
   lines.push(yellow('USAGE'));
-  lines.push(`  $ ${config.name} ${commandName} [options]`);
+  const positionalsPart = buildPositionalsUsage(command.positionals);
+  const usageParts = [
+    `$ ${config.name} ${commandName}`,
+    '[options]',
+    positionalsPart,
+  ]
+    .filter(Boolean)
+    .join(' ');
+  lines.push(`  ${usageParts}`);
   lines.push('');
 
   // Command options

src/types.ts

@@ -338,5 +338,7 @@ interface OptionBase {
  */
 interface PositionalBase {
   description?: string;
+  /** Display name for help text (defaults to arg0, arg1, etc.) */
+  name?: string;
   required?: boolean;
 }

test/help.test.ts

@@ -133,6 +133,59 @@ describe('generateHelp', () => {
   });
 });
 
+describe('generateHelp positionals', () => {
+  it('shows positionals in usage line with default names', () => {
+    const help = stripAnsi(
+      generateHelp({
+        name: 'my-cli',
+        positionals: [opt.stringPos({ required: true }), opt.stringPos()],
+      }),
+    );
+
+    assert.ok(help.includes('<arg0>'));
+    assert.ok(help.includes('[arg1]'));
+  });
+
+  it('shows positionals with custom names', () => {
+    const help = stripAnsi(
+      generateHelp({
+        name: 'my-cli',
+        positionals: [
+          opt.stringPos({ name: 'source', required: true }),
+          opt.stringPos({ name: 'dest' }),
+        ],
+      }),
+    );
+
+    assert.ok(help.includes('<source>'));
+    assert.ok(help.includes('[dest]'));
+  });
+
+  it('shows variadic positionals with ellipsis', () => {
+    const help = stripAnsi(
+      generateHelp({
+        name: 'my-cli',
+        positionals: [opt.variadic('string', { name: 'files' })],
+      }),
+    );
+
+    assert.ok(help.includes('[files...]'));
+  });
+
+  it('shows positional with default as required (angle brackets)', () => {
+    const help = stripAnsi(
+      generateHelp({
+        name: 'my-cli',
+        positionals: [opt.stringPos({ default: 'foo', name: 'input' })],
+      }),
+    );
+
+    // Positionals with defaults are considered "required" in terms of display
+    // because they always have a value
+    assert.ok(help.includes('<input>'));
+  });
+});
+
 describe('generateCommandHelp', () => {
   it('generates help for a specific command', () => {
     const help = stripAnsi(
@@ -179,4 +232,28 @@ describe('generateCommandHelp', () => {
 
     assert.ok(help.includes('Unknown command: unknown'));
   });
+
+  it('shows command positionals with custom names', () => {
+    const help = stripAnsi(
+      generateCommandHelp(
+        {
+          commands: {
+            copy: opt.command({
+              description: 'Copy files',
+              handler: () => {},
+              positionals: [
+                opt.stringPos({ name: 'source', required: true }),
+                opt.stringPos({ name: 'dest', required: true }),
+              ],
+            }),
+          },
+          name: 'my-cli',
+        },
+        'copy',
+      ),
+    );
+
+    assert.ok(help.includes('<source>'));
+    assert.ok(help.includes('<dest>'));
+  });
 });