argsbarg 1.1.1 → 1.2.1

package/.github/copilot-instructions.md.md

@@ -0,0 +1,8 @@
+---
+description: Project context for AI agents
+---
+
+Always include in context before answering or making changes in this repository:
+
+- `README.md`
+- `.cursor/rules/*`

package/.github/pull_request_template.md

@@ -0,0 +1,13 @@
+## Summary
+
+<!-- What does this PR change and why? -->
+
+## Changelog
+
+**Every PR must update `CHANGELOG.md` under `## [Unreleased]`**: use `### Added`, `### Changed`, `### Fixed`, or `### Removed` as appropriate; one idea per bullet.
+
+<!-- If you claimed no-op above, briefly say why no changelog entry is warranted. -->
+
+## Testing
+
+<!-- How did you verify this (local build, tests, manual run, etc.)? -->

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.1] - 2026-06-18
+
+### Changed
+
+- **Trailing options** — when a leaf command has only bounded positionals (`argMax !== 0`), options may appear after positional arguments (e.g. `cmd ./file --verbose`). Commands with a varargs tail (`argMax: 0`) keep the previous behavior.
+- **`examples/nested.ts`** — `stat` accepts `--json`; `stat owner lookup` prints JSON when the flag is set.
+
+## [1.2.0] - 2026-04-24
+
+### Added
+
+- **`CliOption.required`** — makes an option required when parsing
+- **`isInteractiveTty`** - a computed boolean of whether the app is running in an interactive tty
+- **Single-command CLI support** - You can now define a `handler` directly on the root of your CLI configuration to quickly build single-command apps without nesting them in subcommands.
+
+### Changed
+
+- **`CliCommand` Strict Union** - (Breaking TS Change) `CliCommand` is now a Discriminated Union type. A command must be *either* a Router (with `commands`) or a Leaf (with `handler`), but not both. This catches structural mistakes at compile time.
+
 ## [1.1.1] - 2026-04-23
 
 ### Changed
@@ -52,7 +71,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v1.1.1...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v1.2.1...HEAD
+[1.2.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.2.1
+[1.2.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.2.0
 [1.1.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.1.1
 [1.1.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.1.0
 [1.0.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.0.1

package/CLAUDE.md

@@ -0,0 +1,8 @@
+---
+description: Project context for AI agents
+---
+
+Always include in context before answering or making changes in this repository:
+
+- `./README.md`
+- .cursor/rules/*

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian Dombrowski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -29,40 +29,35 @@ Shell completions! -->
 ## Usage
 
 ```typescript
-import { cliRun, CliCommand, CliOptionKind, CliFallbackMode } from "argsbarg";
+import { cliRun, CliCommand, CliOptionKind } from "argsbarg";
 
 const cli: CliCommand = {
   key: "helloapp",
   description: "Tiny demo.",
-  commands: [
+  positionals: [
     {
-      key: "hello",
-      description: "Say hello.",
-      options: [
-        {
-          name: "name",
-          description: "Who to greet.",
-          kind: CliOptionKind.String,
-          shortName: "n",
-        },
-        {
-          name: "verbose",
-          description: "Enable extra logging.",
-          kind: CliOptionKind.Presence,
-          shortName: "v",
-        },
-      ],
-      handler: async (ctx) => {
-        const name = ctx.stringOpt("name") ?? "world";
-        if (ctx.flag("verbose")) { 
-          console.log("verbose mode"); 
-        }
-        console.log(`hello ${name}`);
-      },
+      name: "name",
+      description: "Who to greet.",
+      kind: CliOptionKind.String,
+      argMin: 0,
+      argMax: 1,
     },
   ],
-  fallbackCommand: "hello",
-  fallbackMode: CliFallbackMode.MissingOrUnknown,
+  options: [
+    {
+      name: "verbose",
+      description: "Enable extra logging.",
+      kind: CliOptionKind.Presence,
+      shortName: "v",
+    },
+  ],
+  handler: async (ctx) => {
+    const name = ctx.args[0] ?? "world";
+    if (ctx.hasFlag("verbose")) { 
+      console.log("verbose mode"); 
+    }
+    console.log(`hello ${name}`);
+  },
 };
 
 await cliRun(cli);

package/examples/minimal.ts

@@ -7,40 +7,35 @@ readers can copy the pattern into their own scripts quickly.
 It demonstrates the minimal Bun integration path.
 */
 
-import { cliRun, CliCommand, CliOptionKind, CliFallbackMode } from "../src/index.ts";
+import { cliRun, CliCommand, CliOptionKind } from "../src/index.ts";
 
 const cli: CliCommand = {
   key: "minimal.ts",
   description: "Tiny demo.",
-  commands: [
+  positionals: [
     {
-      key: "hello",
-      description: "Say hello.",
-      options: [
-        {
-          name: "name",
-          description: "Who to greet.",
-          kind: CliOptionKind.String,
-          shortName: "n",
-        },
-        {
-          name: "verbose",
-          description: "Enable extra logging.",
-          kind: CliOptionKind.Presence,
-          shortName: "v",
-        },
-      ],
-      handler: (ctx) => {
-        const name = ctx.stringOpt("name") ?? "world";
-        if (ctx.hasFlag("verbose")) {
-          console.log("verbose mode");
-        }
-        console.log(`hello ${name}`);
-      },
+      name: "name",
+      description: "Who to greet.",
+      kind: CliOptionKind.String,
+      argMin: 0,
+      argMax: 1,
     },
   ],
-  fallbackCommand: "hello",
-  fallbackMode: CliFallbackMode.MissingOrUnknown,
+  options: [
+    {
+      name: "verbose",
+      description: "Enable extra logging.",
+      kind: CliOptionKind.Presence,
+      shortName: "v",
+    },
+  ],
+  handler: (ctx) => {
+    const name = ctx.args[0] ?? "world";
+    if (ctx.hasFlag("verbose")) {
+      console.log("verbose mode");
+    }
+    console.log(`hello ${name}`);
+  },
 };
 
 await cliRun(cli);

package/examples/nested.ts

@@ -16,6 +16,13 @@ const cli: CliCommand = {
     {
       key: "stat",
       description: "File metadata.",
+      options: [
+        {
+          name: "json",
+          description: "Emit handler output as JSON.",
+          kind: CliOptionKind.Presence,
+        },
+      ],
       commands: [
         {
           key: "owner",
@@ -46,7 +53,11 @@ const cli: CliCommand = {
                   console.error("Missing path.");
                   process.exit(1);
                 }
-                console.log(`lookup user=${user} path=${path}`);
+                if (ctx.hasFlag("json")) {
+                  console.log(JSON.stringify({ user, path }));
+                } else {
+                  console.log(`lookup user=${user} path=${path}`);
+                }
               },
             },
           ],

package/examples/option-required.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env bun
+/*
+This example shows the smallest end-to-end CLI setup.
+It includes one command, a couple of options, and a direct call to the runtime so
+readers can copy the pattern into their own scripts quickly.
+
+It demonstrates the minimal Bun integration path.
+*/
+
+import { cliRun, CliCommand, CliOptionKind, CliFallbackMode, isInteractiveTty } from "../src/index.ts";
+
+const cli: CliCommand = {
+  key: "option-required.ts",
+  description: "Demo of a required option.",
+  options: [
+    {
+      name: "requiredAlways",
+      description: "Always required string option.",
+      kind: CliOptionKind.String,
+      required: true,
+      shortName: "a",
+    },
+    {
+      name: "requiredNonTty",
+      description: "Required when not running in a tty.",
+      kind: CliOptionKind.String,
+      required: !isInteractiveTty,
+      shortName: "t",
+    },
+    {
+      name: "optional",
+      description: "optional string option.",
+      kind: CliOptionKind.String,
+      shortName: "o",
+    },
+  ],
+  handler: (ctx) => {
+    const requiredAlways = ctx.stringOpt("requiredAlways")!;
+    const requiredNonTty = ctx.stringOpt("requiredNonTty") ?? "valueWhenOmitted";
+    const optional = ctx.stringOpt("optional") ?? "valueWhenOmitted";
+    console.log(`requiredAlways: ${requiredAlways}`);
+    console.log(`requiredNonTty: ${requiredNonTty}`);
+    console.log(`optional: ${optional}`);
+  },
+};
+
+await cliRun(cli);

package/index.d.ts

@@ -42,6 +42,8 @@ export interface CliOption {
 	kind: CliOptionKind;
 	/** Short option character (e.g., 'n' for -n). */
 	shortName?: string;
+	/** Whether this option must be provided. Cannot be used with Presence kind. */
+	required?: boolean;
 }
 /**
  * An ordered positional argument slot, listed on `CliCommand.positionals`.
@@ -65,13 +67,9 @@ export interface CliPositional {
 	argMax?: number;
 }
 /**
- * A command node: routing group (has commands) or leaf (has handler).
- *
- * The value passed to cliRun is the program root: name is the app/binary name,
- * commands are top-level subcommands, options are global flags.
- * The root must not set handler or declare positionals (validated at startup).
+ * Base properties shared by all command nodes.
  */
-export interface CliCommand {
+export interface CliCommandBase {
 	/** Program or command key (e.g., "myapp", "stat", "owner"). */
 	key: string;
 	/** Short description shown in help. */
@@ -80,17 +78,36 @@ export interface CliCommand {
 	notes?: string;
 	/** Global or command-level flags/options. */
 	options?: CliOption[];
+}
+/**
+ * A command node: either a routing group (has commands) or a leaf (has handler).
+ *
+ * The value passed to cliRun is the program root: name is the app/binary name.
+ * The root may be a routing group or a leaf command.
+ */
+export type CliCommand = (CliCommandBase & {
+	/** Handler function for leaf commands. */
+	handler: CliHandler;
 	/** Positional argument definitions. */
 	positionals?: CliPositional[];
 	/** Nested subcommands (empty for leaf commands). */
-	commands?: CliCommand[];
-	/** Handler function for leaf commands. */
-	handler?: CliHandler;
-	/** Default top-level subcommand when argv omits a command or uses an unknown first token (root only). */
+	commands?: never;
+	/** Default top-level subcommand (routing commands only). */
+	fallbackCommand?: never;
+	/** How fallbackCommand is applied (routing commands only). */
+	fallbackMode?: never;
+}) | (CliCommandBase & {
+	/** Nested subcommands. */
+	commands: CliCommand[];
+	/** Default top-level subcommand when argv omits a command or uses an unknown first token. */
 	fallbackCommand?: string;
-	/** How fallbackCommand is applied (root only). */
+	/** How fallbackCommand is applied. */
 	fallbackMode?: CliFallbackMode;
-}
+	/** Handler function (leaf commands only). */
+	handler?: never;
+	/** Positional argument definitions (leaf commands only). */
+	positionals?: never;
+});
 /**
  * Handler closure type for leaf commands.
  * Supports both sync and async handlers.
@@ -137,5 +154,7 @@ export declare function cliRun(root: CliCommand, argv?: string[]): Promise<never
  * Prints a red error line and contextual help on stderr, then exits with status 1.
  */
 export declare function cliErrWithHelp(ctx: CliContext, msg: string): never;
+/** True when stdin is a TTY. */
+export declare const isInteractiveTty: boolean;
 
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "type": "module",
   "scripts": {
     "//just": "echo this app uses justfile for development tasks"

package/src/help.ts

@@ -64,8 +64,8 @@ function getHelpWidth(): number {
 }
 
 /** True when stdout is a TTY (used to decide on color). */
-function isTTY(): boolean {
-  return process.stdout.isTTY !== undefined;
+function isStdoutTTY(): boolean {
+  return !!process.stdout.isTTY;
 }
 
 // ── Width Helpers ─────────────────────────────────────────────────────────────
@@ -343,7 +343,8 @@ function rowsForOptions(defs: CliOption[], color: boolean): HelpRow[] {
     : "--help, -h";
   rows.push({ label: helpLabel, description: "Show help for this command." });
   for (const o of defs) {
-    rows.push({ label: cliOptionLabel(o, color), description: o.description });
+    const desc = o.required ? "(required) " + o.description : o.description;
+    rows.push({ label: cliOptionLabel(o, color), description: desc });
   }
   return rows;
 }
@@ -368,7 +369,7 @@ function rowsForSubcommands(cmds: CliCommand[]): HelpRow[] {
  */
 export function cliHelpRender(schema: CliCommand, helpPath: string[], useStderr: boolean): string {
   const hw = getHelpWidth();
-  const color = isTTY();
+  const color = isStdoutTTY();
 
   if (helpPath.length === 0) {
     const lines: string[] = [];

package/src/index.test.ts

@@ -12,6 +12,7 @@ import { CliCommand, CliFallbackMode, CliOptionKind } from "./index.ts";
 import { ParseKind, parse, postParseValidate } from "./parse.ts";
 import { cliValidateRoot } from "./validate.ts";
 import { expect, test } from "bun:test";
+import { $ } from "bun";
 
 test("bundled short presence flags", () => {
   const root: CliCommand = {
@@ -175,33 +176,7 @@ test("supports scientific notation in numbers", () => {
   expect(Number(pr.opts["n"])).toBe(12300);
 });
 
-test("root must not have handler", () => {
-  const root: CliCommand = {
-    key: "app",
-    description: "",
-    commands: [{ key: "x", description: "", handler: () => {} }],
-    handler: () => {},
-  };
-  expect(() => cliValidateRoot(root)).toThrow(/Program root must not set handler/);
-});
 
-test("root must not have positionals", () => {
-  const root: CliCommand = {
-    key: "app",
-    description: "",
-    positionals: [
-      {
-        name: "p",
-        description: "",
-        kind: CliOptionKind.String,
-        argMin: 1,
-        argMax: 1,
-      },
-    ],
-    commands: [{ key: "x", description: "", handler: () => {} }],
-  };
-  expect(() => cliValidateRoot(root)).toThrow(/Program root must not declare positionals/);
-});
 
 test("completion scripts contain app name", () => {
   const root: CliCommand = {
@@ -263,6 +238,123 @@ test("completion scripts keep dotted app names in registration names", () => {
   expect(zsh).toContain("compdef _minimal_ts minimal.ts");
 });
 
+test("trailing options after bounded positionals", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "x",
+        description: "cmd",
+        options: [
+          {
+            name: "verbose",
+            description: "",
+            kind: CliOptionKind.Presence,
+          },
+        ],
+        positionals: [
+          {
+            name: "path",
+            description: "",
+            kind: CliOptionKind.String,
+          },
+        ],
+        handler: () => {},
+      },
+    ],
+  };
+  cliValidateRoot(root);
+  const pr = postParseValidate(root, parse(root, ["x", "./file", "--verbose"]));
+  expect(pr.kind).toBe(ParseKind.Ok);
+  expect(pr.args).toEqual(["./file"]);
+  expect(pr.opts["verbose"]).toBe("1");
+});
+
+test("trailing options include parent-scoped flags", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "group",
+        description: "group",
+        options: [
+          {
+            name: "json",
+            description: "",
+            kind: CliOptionKind.Presence,
+          },
+        ],
+        commands: [
+          {
+            key: "leaf",
+            description: "leaf",
+            options: [
+              {
+                name: "user",
+                description: "",
+                kind: CliOptionKind.String,
+                shortName: "u",
+              },
+            ],
+            positionals: [
+              {
+                name: "path",
+                description: "",
+                kind: CliOptionKind.String,
+              },
+            ],
+            handler: () => {},
+          },
+        ],
+      },
+    ],
+  };
+  cliValidateRoot(root);
+  const pr = postParseValidate(root, parse(root, ["group", "leaf", "-u", "alice", "./file", "--json"]));
+  expect(pr.kind).toBe(ParseKind.Ok);
+  expect(pr.path).toEqual(["group", "leaf"]);
+  expect(pr.args).toEqual(["./file"]);
+  expect(pr.opts["user"]).toBe("alice");
+  expect(pr.opts["json"]).toBe("1");
+});
+
+test("varargs tail does not parse trailing options", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "x",
+        description: "cmd",
+        options: [
+          {
+            name: "json",
+            description: "",
+            kind: CliOptionKind.Presence,
+          },
+        ],
+        positionals: [
+          {
+            name: "files",
+            description: "",
+            kind: CliOptionKind.String,
+            argMin: 0,
+            argMax: 0,
+          },
+        ],
+        handler: () => {},
+      },
+    ],
+  };
+  cliValidateRoot(root);
+  const pr = postParseValidate(root, parse(root, ["x", "./file", "--json"]));
+  expect(pr.kind).toBe(ParseKind.Ok);
+  expect(pr.args).toEqual(["./file", "--json"]);
+  expect(pr.opts["json"]).toBeUndefined();
+});
+
 test("stops parsing options at --", () => {
   const root: CliCommand = {
     key: "app",
@@ -296,4 +388,90 @@ test("stops parsing options at --", () => {
   expect(pr.kind).toBe(ParseKind.Ok);
   expect(pr.opts["name"]).toBe("pat");
   expect(pr.args).toEqual(["--name", "bob", "-x"]);
+});
+
+test("missing required option returns error", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "",
+    options: [
+      {
+        name: "req",
+        description: "",
+        kind: CliOptionKind.String,
+        required: true,
+      },
+    ],
+    commands: [
+      {
+        key: "x",
+        description: "cmd",
+        handler: () => {},
+      },
+    ],
+  };
+  cliValidateRoot(root);
+  const pr = postParseValidate(root, parse(root, ["x"]));
+  expect(pr.kind).toBe(ParseKind.Error);
+  expect(pr.errorMsg).toContain("Missing required option: --req");
+});
+
+test("provided required option parses ok", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "x",
+        description: "cmd",
+        options: [
+          {
+            name: "req",
+            description: "",
+            kind: CliOptionKind.String,
+            required: true,
+          },
+        ],
+        handler: () => {},
+      },
+    ],
+  };
+  cliValidateRoot(root);
+  const pr = postParseValidate(root, parse(root, ["x", "--req", "val"]));
+  expect(pr.kind).toBe(ParseKind.Ok);
+  expect(pr.opts["req"]).toBe("val");
+});
+
+test("presence option cannot be required", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "",
+    options: [
+      {
+        name: "flag",
+        description: "",
+        kind: CliOptionKind.Presence,
+        required: true,
+      },
+    ],
+    commands: [
+      {
+        key: "x",
+        description: "cmd",
+        handler: () => {},
+      },
+    ],
+  };
+  expect(() => cliValidateRoot(root)).toThrow(/Presence option cannot be required/);
+});
+
+test("leaf completion help prints correctly", async () => {
+  // Test the fix where `completion zsh -h` on a leaf root was incorrectly ignored.
+  // We run this as a subprocess so we don't accidentally exit the test runner.
+  const { stdout, stderr, exitCode } = await $`bun run examples/minimal.ts completion zsh -h`.nothrow().quiet();
+  const out = stdout.toString();
+  expect(exitCode).toBe(0);
+  expect(out).toContain("Show help for this command.");
+  expect(out).toContain("Output is the whole script.");
+  expect(stderr.toString()).toBe("");
 });

package/src/index.ts

@@ -11,3 +11,4 @@ export { CliContext } from "./context.ts";
 export { cliErrWithHelp, cliRun } from "./runtime";
 export { CliFallbackMode, CliOptionKind, CliSchemaValidationError } from "./types.ts";
 export type { CliCommand, CliHandler, CliOption, CliPositional } from "./types.ts";
+export { isInteractiveTty } from "./utils.ts";

package/src/parse.ts

@@ -207,6 +207,26 @@ function consumeOptions(
 
 // ── Positional Collection ─────────────────────────────────────────────────────
 
+/** Merges option defs from the program root along the routed command path. */
+function collectOptionDefs(root: CliCommand, path: string[]): CliOption[] {
+  let defs = [...(root.options ?? [])];
+  let cmds = root.commands ?? [];
+
+  for (const seg of path) {
+    const ch = findChild(cmds, seg);
+    if (!ch) break;
+    defs.push(...(ch.options ?? []));
+    cmds = ch.commands ?? [];
+  }
+
+  return defs;
+}
+
+/** True when every positional slot has bounded arity (no `argMax: 0` varargs tail). */
+function allowsTrailingOptions(positionals: CliCommand["positionals"]): boolean {
+  return (positionals ?? []).every((p) => (p.argMax ?? 1) !== 0);
+}
+
 /** Fills `args` for a leaf from `startIdx` according to `node.positionals`. */
 function finishLeaf(
   node: CliCommand,
@@ -214,6 +234,8 @@ function finishLeaf(
   argv: string[],
   path: string[],
   opts: Record<string, string>,
+  optionDefs: CliOption[],
+  forcePositionals: boolean,
 ): ParseResult {
   /** Builds a parse error for positional consumption failures. */
   function errorResult(msg: string): ParseResult {
@@ -243,8 +265,13 @@ function finishLeaf(
         args.push(argv[idx]);
         idx += 1;
       } else if (idx < argv.length) {
-        args.push(argv[idx]);
-        idx += 1;
+        const tok = argv[idx];
+        if (argMin < 1 && tok.startsWith("-")) {
+          // Optional slot: leave `-` tokens for trailing option parsing.
+        } else {
+          args.push(tok);
+          idx += 1;
+        }
       }
       continue;
     }
@@ -269,7 +296,23 @@ function finishLeaf(
   }
 
   if (idx < argv.length) {
-    return errorResult("Unexpected extra arguments");
+    if (forcePositionals || !allowsTrailingOptions(node.positionals)) {
+      return errorResult("Unexpected extra arguments");
+    }
+
+    if (isHelpTok(argv[idx])) {
+      return helpResult(path, true);
+    }
+
+    const tailRep = consumeOptions(optionDefs, false, argv, idx, opts);
+    if (tailRep.report.err) {
+      return errorResult(tailRep.report.err);
+    }
+    idx = tailRep.nextIndex;
+
+    if (idx < argv.length) {
+      return errorResult("Unexpected extra arguments");
+    }
   }
 
   return { kind: ParseKind.Ok, path, opts, args, helpExplicit: false, helpPath: [], errorMsg: "", errorHelpPath: [] };
@@ -328,6 +371,10 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
   let cmdName: string;
   let node: CliCommand | undefined;
 
+  if (root.handler) {
+    return finishLeaf(root as CliCommand, i, argv, path, opts, root.options ?? [], forcePositionals);
+  }
+
   if (i >= argv.length) {
     if (root.fallbackCommand !== undefined && ((root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOnly || (root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOrUnknown)) {
       cmdName = root.fallbackCommand;
@@ -411,7 +458,7 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
       if ((current.commands ?? []).length > 0) {
         return helpResult(path, false);
       }
-      return finishLeaf(current, i, argv, path, opts);
+      return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals);
     }
 
     const tok = argv[i];
@@ -451,7 +498,7 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
       };
     }
 
-    return finishLeaf(current, i, argv, path, opts);
+    return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals);
   }
 }
 
@@ -484,6 +531,21 @@ export function postParseValidate(root: CliCommand, pr: ParseResult): ParseResul
     cmds = ch.commands ?? [];
   }
 
+  for (const d of defs) {
+    if (d.required && !(d.name in pr.opts)) {
+      return {
+        kind: ParseKind.Error,
+        path: pr.path,
+        opts: {},
+        args: [],
+        helpExplicit: false,
+        helpPath: [],
+        errorMsg: `Missing required option: --${d.name}`,
+        errorHelpPath: pr.path,
+      };
+    }
+  }
+
   for (const [k, v] of Object.entries(pr.opts)) {
     const d = findOptionByName(defs, k);
     if (!d) {

package/src/runtime.ts

@@ -18,9 +18,12 @@ import { cliValidateRoot } from "./validate.ts";
  * Merges the caller's program root with the reserved `completion` subtree.
  */
 function cliRootMergedWithBuiltins(root: CliCommand): CliCommand {
-  const merged = { ...root };
+  if (root.handler) {
+    return root;
+  }
+  const merged = { ...root } as any;
   merged.commands = [...(root.commands ?? []), cliBuiltinCompletionGroup(root.key)];
-  return merged;
+  return merged as CliCommand;
 }
 
 /**
@@ -41,12 +44,27 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
     process.exit(1);
   }
 
-  const merged = cliRootMergedWithBuiltins(root);
-  let pr = parse(merged, argv);
-  pr = postParseValidate(merged, pr);
+  let parseRoot = root;
+  let isLeafCompletionIntercept = false;
+
+  // Intercept completion for Leaf roots (since they can't natively have a completion subcommand)
+  // but wrap them in a dummy router so that the parser handles `-h` and errors correctly.
+  if (root.handler && argv.length >= 1 && argv[0] === "completion") {
+    isLeafCompletionIntercept = true;
+    parseRoot = {
+      key: root.key,
+      description: root.description,
+      commands: [cliBuiltinCompletionGroup(root.key)],
+    } as any;
+  } else {
+    parseRoot = cliRootMergedWithBuiltins(root);
+  }
+
+  let pr = parse(parseRoot, argv);
+  pr = postParseValidate(parseRoot, pr);
 
   if (pr.kind === "help") {
-    process.stdout.write(cliHelpRender(merged, pr.helpPath, false));
+    process.stdout.write(cliHelpRender(parseRoot, pr.helpPath, false));
     process.exit(pr.helpExplicit ? 0 : 1);
   }
 
@@ -54,27 +72,28 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
     const color = process.stderr.isTTY;
     const msg = color ? `\u001B[31m${pr.errorMsg}\u001B[0m` : pr.errorMsg;
     process.stderr.write(msg + "\n");
-    process.stderr.write(cliHelpRender(merged, pr.errorHelpPath, true));
+    process.stderr.write(cliHelpRender(parseRoot, pr.errorHelpPath, true));
     process.exit(1);
   }
 
-  if (pr.path.length === 0) {
-    process.stderr.write("Internal error: empty path.\n");
-    process.exit(1);
-  }
+  // Leaf roots have an empty path; that's normal.
 
   if (pr.path[0] === "completion") {
+    // If we intercepted a leaf, we MUST pass the original `root` to generate completions
+    // because `parseRoot` is just a dummy router!
+    const schemaForCompletion = isLeafCompletionIntercept ? root : parseRoot;
+
     if (pr.path[1] === "bash") {
-      process.stdout.write(completionBashScript(merged));
+      process.stdout.write(completionBashScript(schemaForCompletion));
       process.exit(0);
     }
     if (pr.path[1] === "zsh") {
-      process.stdout.write(completionZshScript(merged));
+      process.stdout.write(completionZshScript(schemaForCompletion));
       process.exit(0);
     }
   }
 
-  let current = merged;
+  let current = parseRoot;
   for (const seg of pr.path) {
     const ch = (current.commands ?? []).find((candidate: CliCommand) => candidate.key === seg);
     if (!ch) {
@@ -89,7 +108,7 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
     process.exit(1);
   }
 
-  const ctx = new CliContext(merged.key, pr.path, pr.args, pr.opts, merged);
+  const ctx = new CliContext(parseRoot.key, pr.path, pr.args, pr.opts, parseRoot);
   try {
     await Promise.resolve(current.handler(ctx));
     process.exit(0);

package/src/types.ts

@@ -52,6 +52,8 @@ export interface CliOption {
   kind: CliOptionKind;
   /** Short option character (e.g., 'n' for -n). */
   shortName?: string;
+  /** Whether this option must be provided. Cannot be used with Presence kind. */
+  required?: boolean;
 }
 
 /**
@@ -77,13 +79,9 @@ export interface CliPositional {
 }
 
 /**
- * A command node: routing group (has commands) or leaf (has handler).
- *
- * The value passed to cliRun is the program root: name is the app/binary name,
- * commands are top-level subcommands, options are global flags.
- * The root must not set handler or declare positionals (validated at startup).
+ * Base properties shared by all command nodes.
  */
-export interface CliCommand {
+export interface CliCommandBase {
   /** Program or command key (e.g., "myapp", "stat", "owner"). */
   key: string;
   /** Short description shown in help. */
@@ -92,18 +90,40 @@ export interface CliCommand {
   notes?: string;
   /** Global or command-level flags/options. */
   options?: CliOption[];
-  /** Positional argument definitions. */
-  positionals?: CliPositional[];
-  /** Nested subcommands (empty for leaf commands). */
-  commands?: CliCommand[];
-  /** Handler function for leaf commands. */
-  handler?: CliHandler;
-  /** Default top-level subcommand when argv omits a command or uses an unknown first token (root only). */
-  fallbackCommand?: string;
-  /** How fallbackCommand is applied (root only). */
-  fallbackMode?: CliFallbackMode;
 }
 
+/**
+ * A command node: either a routing group (has commands) or a leaf (has handler).
+ *
+ * The value passed to cliRun is the program root: name is the app/binary name.
+ * The root may be a routing group or a leaf command.
+ */
+export type CliCommand =
+  | (CliCommandBase & {
+      /** Handler function for leaf commands. */
+      handler: CliHandler;
+      /** Positional argument definitions. */
+      positionals?: CliPositional[];
+      /** Nested subcommands (empty for leaf commands). */
+      commands?: never;
+      /** Default top-level subcommand (routing commands only). */
+      fallbackCommand?: never;
+      /** How fallbackCommand is applied (routing commands only). */
+      fallbackMode?: never;
+    })
+  | (CliCommandBase & {
+      /** Nested subcommands. */
+      commands: CliCommand[];
+      /** Default top-level subcommand when argv omits a command or uses an unknown first token. */
+      fallbackCommand?: string;
+      /** How fallbackCommand is applied. */
+      fallbackMode?: CliFallbackMode;
+      /** Handler function (leaf commands only). */
+      handler?: never;
+      /** Positional argument definitions (leaf commands only). */
+      positionals?: never;
+    });
+
 /**
  * Handler closure type for leaf commands.
  * Supports both sync and async handlers.

package/src/utils.ts

@@ -22,3 +22,6 @@ export function strictParseDouble(s: string): number | null {
   const num = Number(s);
   return Number.isNaN(num) ? null : num;
 }
+
+/** True when stdin is a TTY. */
+export const isInteractiveTty = !!process.stdin.isTTY;

package/src/validate.ts

@@ -9,6 +9,7 @@ It fails early on structural problems so invalid trees never reach parsing or di
 import {
   CliCommand,
   CliFallbackMode,
+  CliOptionKind,
   CliSchemaValidationError,
 } from "./types.ts";
 
@@ -19,13 +20,6 @@ const reservedCommandNames = ["completion"];
  * Throws CliSchemaValidationError if rules are violated.
  */
 export function cliValidateRoot(root: CliCommand): void {
-  // Root-level rules
-  if (root.handler !== undefined) {
-    throw new CliSchemaValidationError("Program root must not set handler");
-  }
-  if ((root.positionals ?? []).length > 0) {
-    throw new CliSchemaValidationError("Program root must not declare positionals");
-  }
 
   // Check for reserved command names at root
   for (const child of root.commands ?? []) {
@@ -56,15 +50,6 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
     );
   }
 
-  if ((cmd.commands ?? []).length > 0) {
-    if (cmd.handler !== undefined) {
-      throw new CliSchemaValidationError(`Routing command must not set handler: ${cmd.key}`);
-    }
-  } else {
-    if (cmd.handler === undefined) {
-      throw new CliSchemaValidationError(`Leaf command requires handler: ${cmd.key}`);
-    }
-  }
 
   // Check for duplicate child names
   const seenNames = new Set<string>();
@@ -75,9 +60,15 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
     seenNames.add(child.key);
   }
 
-  // Validate options (short name uniqueness, reserved -h)
+  // Validate options (short name uniqueness, reserved -h, required presence)
   const seenShorts = new Set<string>();
   for (const opt of cmd.options ?? []) {
+    if (opt.required && opt.kind === CliOptionKind.Presence) {
+      throw new CliSchemaValidationError(
+        `Presence option cannot be required: ${cmd.key}/${opt.name}`,
+      );
+    }
+
     if (opt.shortName !== undefined) {
       if (opt.shortName === "h") {
         throw new CliSchemaValidationError(