argsbarg 6.1.0 → 6.1.2

package/CHANGELOG.md

@@ -7,12 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.1.2] - 2026-07-23
+
+### Added
+
+- **`kind: "json"` on `CliLeaf`** — pure JSON body leaves with no CLI flags. Requires `inputSchema`; forbids `options` and `positionals`. CLI accepts one JSON positional or piped stdin; MCP/HTTP use the tool args object directly. **`isJsonLeaf()`** helper exported.
+
+## [6.1.1] - 2026-07-23
+
+### Added
+
+- **`ctx.inputs`** — coerced, pre-validated leaf inputs (getter; preferred over `readLeafInputs()`).
+- **`ctx.inputsAs<T>()`** — `ctx.inputs` cast to a schemagen or app input type (`T` unconstrained; consumer-asserted).
+
+### Changed
+
+- **`leaf.inputSchema` validation** — runs before the leaf handler in `Cli.run()` and `Cli.invoke()` (same JSON Schema subset as `program.appConfig`). `LeafInputError` prints contextual help on CLI. `ctx.inputs` returns the cached, pre-validated result.
+- **`ctx.readLeafInputs()`** — deprecated; use `ctx.inputs` or `ctx.inputsAs()`.
+
 ## [6.1.0] - 2026-07-22
 
 ### Added
 
 - **`CliOptionKind.Json`** and **`pipable`** — JSON object options with CLI `--name '<json>'` or piped stdin when the flag is omitted (flag wins if set). MCP/API values merge from `toolArgs`.
-- **`ctx.readLeafInputsAsync()`** — resolves Json options (flag, stdin, or `toolArgs`) and validates against `leaf.inputSchema` when set.
+- **`ctx.jsonOpt(name)`** — parsed Json option from flag, preloaded stdin, or MCP/API `toolArgs`.
+- **`ctx.readLeafInputs()`** — all coerced inputs; validates against `leaf.inputSchema` when set (stdin preloaded before handler).
+- **`ctx.readLeafInputsAsync()`** — deprecated alias for sync `readLeafInputs()`.
 
 ### Changed
 
@@ -750,7 +770,9 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - 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/v6.1.0...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.1.2...HEAD
+[6.1.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.2
+[6.1.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.1
 [6.1.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.0
 [6.0.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.0.2
 [6.0.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.0.1

package/README.md

@@ -207,8 +207,11 @@ Add `CliPositional` entries to the command’s `positionals` list (separate from
 - `ctx.durationOpt("timeout")` — duration options (`format: CliValueFormat.Duration`) as milliseconds.
 - `ctx.commaListOpt("services")` — comma-list options as `string[] | undefined`.
 - `ctx.dateOpt("on")` / `ctx.dateTimeOpt("since")` — ISO date / date-time options.
-- `ctx.readLeafInputs()` — coerced option and positional values for the current leaf (schema-driven).
-- `ctx.readLeafInputsAsync()` — like `readLeafInputs()`, plus Json options (flag, piped stdin, MCP `toolArgs`) and `inputSchema` validation.
+- `ctx.inputs` — coerced option and positional values for the current leaf; when `inputSchema` is set, validated before the handler runs and cached on `ctx`.
+- `ctx.inputsAs<T>()` — `ctx.inputs` cast to a schemagen or app input type.
+- `ctx.readLeafInputs()` — deprecated; use `ctx.inputs` or `ctx.inputsAs()`.
+- `ctx.jsonOpt(name)` — parsed Json option (flag, preloaded stdin, or MCP/API `toolArgs`).
+- `ctx.readLeafInputsAsync()` — deprecated alias for `readLeafInputs()`.
 - `ctx.typedOpt<T>("custom", parseFn)` — custom parsing for type-safe option resolution.
 - `ctx.args` — positional words in order as `string[]`.
 - `ctx.positional("name")` — named positional lookup; varargs slots return `string[]`, single slots return `string | undefined`.

package/docs/api-server.md

@@ -138,4 +138,4 @@ Call `generateOpenApi(program)` or `openApiJson(program)` from the package, fetc
 
 ## Complex tool inputs
 
-For nested request bodies (e.g. invoice template data), set `inputSchema` on the leaf, declare a matching `kind: Json` option (optionally `pipable: true` for CLI stdin), and read inputs with `await ctx.readLeafInputsAsync()` — it merges flag values, piped stdin, and the original flat JSON body from `POST /tools/:name`.
+For nested request bodies (e.g. invoice template data), set `inputSchema` on the leaf, declare a matching `kind: Json` option (optionally `pipable: true` for CLI stdin), and read inputs with `ctx.jsonOpt(...)` or `ctx.readLeafInputs()` — piped stdin is loaded before the handler runs.

package/docs/cli-program.md

@@ -203,14 +203,17 @@ handler: async (ctx) => {
 
 Read varargs with `ctx.positional("uids")` (returns `string[]`) or `ctx.args`. Do not comma-split argv tokens or use `format` on positionals.
 
-**`readLeafInputs()`** — for leaves with several flags, one schema-driven read instead of hand-rolled `hasFlag` / `stringOpt` lines:
+**`ctx.inputs`** — coerced option and positional values for the current leaf. When `leaf.inputSchema` is set, argsbarg validates **before the handler runs** and caches the result on `ctx`:
 
 ```typescript
-const { limit, "skip-readiness": skipReadiness, timeout } = ctx.readLeafInputs();
-// duration → number (ms); comma-list → string[]; presence → boolean; number → number
+const { limit, "skip-readiness": skipReadiness, timeout } = ctx.inputs;
+// or, with a schemagen type:
+const { format, invoice } = ctx.inputsAs<RenderInvoiceInput>();
 ```
 
-**`CliLeafInputs`** — return type of `readLeafInputs()` (exported from `"argsbarg"`). A flat record keyed by **schema option and positional names** (hyphens preserved, e.g. `"skip-readiness"`). Values are coerced per kind/format:
+**`readLeafInputs()`** — deprecated alias for `ctx.inputs`.
+
+**`CliLeafInputs`** — return type of `ctx.inputs` (exported from `"argsbarg"`). A flat record keyed by **schema option and positional names** (hyphens preserved, e.g. `"skip-readiness"`). Values are coerced per kind/format:
 
 | Schema | Value in `CliLeafInputs` |
 | --- | --- |
@@ -223,9 +226,9 @@ const { limit, "skip-readiness": skipReadiness, timeout } = ctx.readLeafInputs()
 | `format: date-time` | `string` (normalized UTC ISO) |
 | Single positional | `string` or `undefined` |
 | Varargs positional | `string[]` or `undefined` |
-| `kind: json` | parsed object/array or `undefined` (use `readLeafInputsAsync()` for pipable stdin and MCP merge) |
+| `kind: json` | parsed object/array or `undefined` (`ctx.jsonOpt(name)`; piped stdin preloaded before handler) |
 
-Omitted options appear as `undefined` (not absent keys). Options with `default` are filled in post-parse before handlers run, so `readLeafInputs()` and `durationOpt` see defaults. **`ctx.opts` always holds raw strings** — use typed accessors or `readLeafInputs()` for coerced values.
+Omitted options appear as `undefined` (not absent keys). Options with `default` are filled in post-parse before handlers run, so `ctx.inputs` and `durationOpt` see defaults. **`ctx.opts` always holds raw strings** — use typed accessors or `ctx.inputs` for coerced values.
 
 ### Json options and piped stdin
 
@@ -243,15 +246,39 @@ For nested tool bodies (e.g. invoice template data), declare a matching property
 
 | Surface | How `invoice` is supplied |
 | --- | --- |
-| CLI | `--invoice '<json>'` **or** omit the flag and pipe JSON to stdin |
+| CLI | `--invoice '<json>'` **or** omit the flag and pipe JSON to stdin (preloaded before the handler) |
 | MCP / HTTP | `invoice` object in the tool JSON body (`ctx.toolArgs`) |
 
 **Precedence:** if `--invoice` is set, the flag value wins and stdin is not read.
 
-Use **`await ctx.readLeafInputsAsync()`** (not sync `readLeafInputs()`) so Json options resolve from flags, piped stdin, or `toolArgs`. When `leaf.inputSchema` is set, argsbarg validates the merged inputs (same JSON Schema subset as `program.appConfig`).
+Use **`ctx.jsonOpt("invoice")`**, **`ctx.inputs`**, or **`ctx.inputsAs<MyInput>()`** — all synchronous. Argsbarg reads piped stdin before calling the handler when a `pipable` Json flag is omitted. When `leaf.inputSchema` is set, argsbarg validates merged inputs **before the handler runs** (same JSON Schema subset as `program.appConfig`); `ctx.inputs` returns the cached result.
 
 At most one `pipable` Json option per leaf. Json option names must appear in `inputSchema.properties` when a custom `inputSchema` is set.
 
+### Pure JSON leaves (`kind: "json"`)
+
+When the entire tool body is JSON (no CLI flags), set **`kind: "json"`** on the leaf with **`inputSchema`** and **no `options` or `positionals`**:
+
+```typescript
+{
+  key: "render-invoice",
+  description: "Render an invoice from template data",
+  kind: "json",
+  inputSchema,
+  handler: (ctx) => {
+    const { format, invoice } = ctx.inputsAs<RenderInvoiceInput>();
+    // ...
+  },
+}
+```
+
+| Surface | How input is supplied |
+| --- | --- |
+| CLI | One JSON positional **or** pipe a JSON document to stdin |
+| MCP / HTTP | Full tool args object (`ctx.toolArgs` / POST body) |
+
+Example CLI: `jq '{format:"pdf", invoice:.}' data.json | myapp render-invoice`
+
 See [output-schema.md](output-schema.md) for schemagen `inputType` and [api-server.md](api-server.md) for HTTP tool bodies.
 
 `CliLeafInputs` is intentionally untyped at the framework level. Narrow in your app (`read*Flags(ctx)` returning a typed struct) rather than expecting inference from `satisfies CliLeaf`.

package/docs/output-schema.md

@@ -133,7 +133,7 @@ export type outputType = RenderInvoiceOutput;
 
 **Domain helpers** and **role exports** live in `types.ts`. Commands without structured JSON omit role exports. Shared shapes (e.g. `HeadlessOpResult`) are defined once in `types.ts` with a single `outputType`; other commands import `{ outputSchema }` from that module’s `__generated__/index.ts`.
 
-For nested MCP/HTTP bodies, add a `kind: Json` option (same name as the `inputType` property) and use `await ctx.readLeafInputsAsync()` — see [cli-program.md](cli-program.md#json-options-and-piped-stdin).
+For nested MCP/HTTP bodies, add a `kind: Json` option (same name as the `inputType` property) and use `ctx.jsonOpt(...)` or `ctx.readLeafInputs()` — see [cli-program.md](cli-program.md#json-options-and-piped-stdin).
 
 When you do **not** set `inputSchema`, argsbarg builds tool input from CLI `options` + `positionals`.
 

package/index.d.ts

@@ -59,9 +59,12 @@ export declare class CliContext {
 	readonly appConfig: AnyAppConfigSnapshot;
 	/** Original flat tool arguments for API/MCP invocations (when provided). */
 	readonly toolArgs?: Record<string, unknown>;
+	/** Pipable Json option values read from stdin before the handler (CLI only). */
+	readonly preloadedJson: Record<string, unknown>;
 	private response?;
+	private leafInputsCache?;
 	/** Captures the program root, routed path, positional words, and option map for a leaf handler. */
-	constructor(appName: string, commandPath: string[], args: string[], opts: Record<string, string>, program: CliProgram, invocation?: CliInvocation, appConfig?: AnyAppConfigSnapshot, toolArgs?: Record<string, unknown>);
+	constructor(appName: string, commandPath: string[], args: string[], opts: Record<string, string>, program: CliProgram, invocation?: CliInvocation, appConfig?: AnyAppConfigSnapshot, toolArgs?: Record<string, unknown>, preloadedJson?: Record<string, unknown>);
 	/**
 	 * Sets the machine-readable response for API/MCP invocations, or writes to stdout in CLI mode.
 	 * May only be called once per invocation.
@@ -88,16 +91,30 @@ export declare class CliContext {
 	dateOpt(name: string): string | undefined;
 	/** Date-time option as normalized ISO 8601 UTC (post-parse validated). */
 	dateTimeOpt(name: string): string | undefined;
+	/**
+	 * Parsed Json option: `--name '<json>'`, preloaded piped stdin (when `pipable`), or MCP/API toolArgs.
+	 * Flag wins over stdin and toolArgs.
+	 */
+	jsonOpt(name: string): unknown | undefined;
 	/** Returns the value(s) for a named positional slot. Varargs slots return string[]; single slots return string | undefined. */
 	positional(name: string): string | string[] | undefined;
-	/** Reads coerced option and positional values for the current leaf from schema metadata. */
+	/**
+	 * Coerced option and positional values for the current leaf.
+	 * When `leaf.inputSchema` is set, argsbarg validates before the handler runs; this returns the cached result.
+	 */
+	get inputs(): CliLeafInputs;
+	/**
+	 * {@link inputs} cast to a schemagen or app-defined input type (consumer-asserted; not inferred from `inputSchema`).
+	 */
+	inputsAs<T = CliLeafInputs>(): T;
+	/**
+	 * @deprecated Use {@link inputs} or {@link inputsAs}.
+	 */
 	readLeafInputs(): CliLeafInputs;
 	/**
-	 * Reads coerced leaf inputs, resolving Json options from flags, piped stdin (when `pipable`),
-	 * or MCP/API toolArgs, and validates against `leaf.inputSchema` when set.
+	 * @deprecated Use sync {@link readLeafInputs} — stdin is preloaded before the handler runs.
 	 */
 	readLeafInputsAsync(): Promise<CliLeafInputs>;
-	private _readOptionValue;
 	private _leafNode;
 	private _posMap;
 	private _positionalMap;
@@ -473,10 +490,17 @@ export interface CliNodeBase {
 	/** Global or command-level flags/options. */
 	options?: CliOption[];
 }
+/** Leaf input mode: `json` = pure JSON body (no CLI flags). */
+export type CliLeafKind = "json";
 /**
  * A leaf command node with a handler and optional positionals.
  */
 export type CliLeaf = CliNodeBase & {
+	/**
+	 * When `"json"`, the leaf accepts a single JSON document (CLI positional or piped stdin;
+	 * MCP/HTTP tool args = body). Requires `inputSchema`; forbids `options` and `positionals`.
+	 */
+	kind?: CliLeafKind;
 	/** Handler function for leaf commands. */
 	handler: CliHandler;
 	/** Positional argument definitions. */
@@ -528,6 +552,8 @@ export type CliProgram = CliNode & {
 	/** When set with `enabled: true`, enables the `docs` built-in command group. */
 	docs?: CliDocsConfig;
 };
+/** True when the leaf accepts a pure JSON body (no CLI flags). */
+export declare function isJsonLeaf(leaf: CliLeaf): boolean;
 /**
  * Handler closure type for leaf commands.
  * Supports sync and async handlers; non-undefined return values become implicit JSON responses for headless invocations.
@@ -596,6 +622,8 @@ export declare class Cli {
 	}): Promise<CliInvokeResult>;
 	serveMcp(): Promise<never>;
 	serveApi(): Promise<never>;
+	private ensureValidatedLeafInputs;
+	private exitLeafInputError;
 	private prepareDispatch;
 	private buildAppConfigSnapshot;
 }
@@ -643,14 +671,25 @@ dryRun?: boolean,
 interactive?: boolean): void;
 /** Prefixes a success message when running in dry-run mode. */
 export declare function formatDryRunMessage(message: string, dryRun: boolean): string;
-/** Thrown when {@link CliContext.readLeafInputsAsync} cannot resolve or validate inputs. */
+/** Thrown when leaf input resolution or validation fails. */
 export declare class LeafInputError extends Error {
 	constructor(message: string);
 }
+/** Resolves a Json option from argv, preloaded stdin, or toolArgs (flag wins). */
+export declare function readJsonOptionValue(ctx: CliContext, name: string): unknown | undefined;
+/**
+ * Reads piped stdin for a pipable Json option when the flag is omitted (CLI only).
+ * Call from {@link Cli.run} before constructing the handler context.
+ */
+export declare function preloadPipableJson(program: CliProgram, commandPath: string[], opts: Record<string, string>, invocation: CliInvocation, args?: string[]): Promise<Record<string, unknown>>;
 /**
- * Reads coerced leaf inputs, resolving Json options from flags, piped stdin, or toolArgs,
- * and validates against `leaf.inputSchema` when set.
+ * Loads coerced leaf inputs and validates against `leaf.inputSchema` when set.
+ * Used by {@link CliContext.inputs}; prefer `ctx.inputs` or `ctx.inputsAs()` in handlers.
  */
+export declare function loadLeafInputs(ctx: CliContext): CliLeafInputs;
+/** @deprecated Use {@link CliContext.inputs} or {@link loadLeafInputs} via `ctx.inputs`. */
+export declare function readLeafInputs(ctx: CliContext): CliLeafInputs;
+/** @deprecated Use sync {@link readLeafInputs} — stdin is preloaded before the handler runs. */
 export declare function readLeafInputsAsync(ctx: CliContext): Promise<CliLeafInputs>;
 /** Resolved paths for `mcp bundle`. */
 export interface McpBundlePaths {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "6.1.0",
+  "version": "6.1.2",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "dependencies": {

package/src/cli.ts

@@ -18,6 +18,7 @@ import { readAppConfigFileRaw, resolveAppConfigPath } from "./config/file.ts";
 import { effectiveJsonSchema } from "./config/schema.ts";
 import { CliContext } from "./context.ts";
 import { cliHelpRender } from "./help.ts";
+import { LeafInputError, preloadPipableJson } from "./leaf-inputs.ts";
 import { bootstrapMcpEnv } from "./mcp/env.ts";
 import { mcpServeStdioLoop } from "./mcp/server.ts";
 import { ParseKind, type ParseResult, parse, postParseValidate } from "./parse.ts";
@@ -124,14 +125,41 @@ export class Cli {
       exitOnMissing: !skipRequiredConfig,
     });
 
-    const ctx = new CliContext(this.program.key, pr.path, pr.args, pr.opts, this.program, "cli", snapshot);
+    let preloadedJson: Record<string, unknown> = {};
     try {
+      preloadedJson = await preloadPipableJson(this.program, pr.path, pr.opts, "cli", pr.args);
+    } catch (err) {
+      if (err instanceof LeafInputError) {
+        this.exitLeafInputError(err, pr.path);
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      const color = process.stderr.isTTY;
+      process.stderr.write(color ? `\u001B[31m${msg}\u001B[0m\n` : `${msg}\n`);
+      process.exit(1);
+    }
+
+    const ctx = new CliContext(
+      this.program.key,
+      pr.path,
+      pr.args,
+      pr.opts,
+      this.program,
+      "cli",
+      snapshot,
+      undefined,
+      preloadedJson,
+    );
+    try {
+      this.ensureValidatedLeafInputs(ctx, leaf);
       const handlerResult = await Promise.resolve(leaf.handler(ctx));
       if (handlerResult !== undefined && ctx.getResponse() === undefined) {
         ctx.respond({ body: handlerResult as CliRespondOptions["body"] });
       }
       process.exit(0);
     } catch (err) {
+      if (err instanceof LeafInputError) {
+        this.exitLeafInputError(err, pr.path);
+      }
       if (err instanceof Error) {
         process.stderr.write(`${err.message}\n`);
       }
@@ -232,6 +260,7 @@ export class Cli {
         });
       }
 
+      this.ensureValidatedLeafInputs(ctx, leaf);
       const handlerResult = await Promise.resolve(leaf.handler(ctx));
       if (handlerResult !== undefined && ctx.getResponse() === undefined) {
         ctx.respond({ body: handlerResult as CliRespondOptions["body"] });
@@ -260,6 +289,15 @@ export class Cli {
         const msg = stderr.trim() || `Exit code ${err.code}`;
         return { kind: "error", exitCode: err.code, stdout, stderr, errorMsg: msg };
       }
+      if (err instanceof LeafInputError) {
+        return {
+          kind: "error",
+          exitCode: 1,
+          stdout,
+          stderr: `${err.message}\n`,
+          errorMsg: err.message,
+        };
+      }
       if (err instanceof Error) {
         return {
           kind: "error",
@@ -320,6 +358,21 @@ export class Cli {
     }
   }
 
+  private ensureValidatedLeafInputs(ctx: CliContext, leaf: CliLeaf): void {
+    if (leaf.inputSchema === undefined) {
+      return;
+    }
+    ctx.inputs;
+  }
+
+  private exitLeafInputError(err: LeafInputError, helpPath: string[]): never {
+    const color = process.stderr.isTTY;
+    const msg = color ? `\u001B[31m${err.message}\u001B[0m` : err.message;
+    process.stderr.write(`${msg}\n`);
+    process.stderr.write(cliHelpRender(this.presentationRoot, helpPath, true));
+    process.exit(1);
+  }
+
   private prepareDispatch(
     argv: string[],
     opts?: { presentationFallback?: boolean },

package/src/context.ts

@@ -10,11 +10,10 @@ parsed values.
 import type { AnyAppConfigSnapshot } from "./config/context.ts";
 import { EmptyAppConfigSnapshot } from "./config/context.ts";
 import { parseCommaList, parseDate, parseDateTime, parseDurationMs } from "./formats.ts";
-import { readLeafInputsAsync as loadLeafInputsAsync } from "./leaf-inputs.ts";
-import { collectOptionDefs } from "./parse.ts";
+import { loadLeafInputs, readJsonOptionValue } from "./leaf-inputs.ts";
 import { normalizeRespondOptions, writeRespondBodyToStdout } from "./respond.ts";
-import type { CliInvocation, CliLeaf, CliNode, CliOption, CliProgram, CliRespondOptions } from "./types.ts";
-import { CliOptionKind, CliValueFormat, isCliLeaf, isCliRouter } from "./types.ts";
+import type { CliInvocation, CliLeaf, CliNode, CliProgram, CliRespondOptions } from "./types.ts";
+import { isCliLeaf, isCliRouter } from "./types.ts";
 import { strictParseDouble } from "./utils.ts";
 
 /** Coerced leaf inputs keyed by option and positional names. */
@@ -33,8 +32,11 @@ export class CliContext {
   readonly appConfig: AnyAppConfigSnapshot;
   /** Original flat tool arguments for API/MCP invocations (when provided). */
   readonly toolArgs?: Record<string, unknown>;
+  /** Pipable Json option values read from stdin before the handler (CLI only). */
+  readonly preloadedJson: Record<string, unknown>;
 
   private response?: CliRespondOptions;
+  private leafInputsCache?: CliLeafInputs;
 
   /** Captures the program root, routed path, positional words, and option map for a leaf handler. */
   constructor(
@@ -46,6 +48,7 @@ export class CliContext {
     invocation: CliInvocation = "cli",
     appConfig: AnyAppConfigSnapshot = new EmptyAppConfigSnapshot(program),
     toolArgs?: Record<string, unknown>,
+    preloadedJson: Record<string, unknown> = {},
   ) {
     this.appName = appName;
     this.commandPath = commandPath;
@@ -55,6 +58,7 @@ export class CliContext {
     this.invocation = invocation;
     this.appConfig = appConfig;
     this.toolArgs = toolArgs;
+    this.preloadedJson = preloadedJson;
   }
 
   /**
@@ -137,71 +141,50 @@ export class CliContext {
     return parseDateTime(s);
   }
 
+  /**
+   * Parsed Json option: `--name '<json>'`, preloaded piped stdin (when `pipable`), or MCP/API toolArgs.
+   * Flag wins over stdin and toolArgs.
+   */
+  jsonOpt(name: string): unknown | undefined {
+    return readJsonOptionValue(this, name);
+  }
+
   /** Returns the value(s) for a named positional slot. Varargs slots return string[]; single slots return string | undefined. */
   positional(name: string): string | string[] | undefined {
     return this._positionalMap()[name];
   }
 
-  /** Reads coerced option and positional values for the current leaf from schema metadata. */
-  readLeafInputs(): CliLeafInputs {
-    const leaf = this._leafNode();
-    if (!leaf) return {};
-
-    const out: CliLeafInputs = {};
-    for (const opt of collectOptionDefs(this.program, this.commandPath)) {
-      out[opt.name] = this._readOptionValue(opt);
-    }
-    for (const p of leaf.positionals ?? []) {
-      const val = this.positional(p.name);
-      if (val === undefined) {
-        out[p.name] = undefined;
-      } else if (Array.isArray(val)) {
-        out[p.name] = val;
-      } else {
-        out[p.name] = val;
-      }
+  /**
+   * Coerced option and positional values for the current leaf.
+   * When `leaf.inputSchema` is set, argsbarg validates before the handler runs; this returns the cached result.
+   */
+  get inputs(): CliLeafInputs {
+    if (this.leafInputsCache !== undefined) {
+      return this.leafInputsCache;
     }
-    return out;
+    this.leafInputsCache = loadLeafInputs(this);
+    return this.leafInputsCache;
   }
 
   /**
-   * Reads coerced leaf inputs, resolving Json options from flags, piped stdin (when `pipable`),
-   * or MCP/API toolArgs, and validates against `leaf.inputSchema` when set.
+   * {@link inputs} cast to a schemagen or app-defined input type (consumer-asserted; not inferred from `inputSchema`).
    */
-  async readLeafInputsAsync(): Promise<CliLeafInputs> {
-    return loadLeafInputsAsync(this);
+  inputsAs<T = CliLeafInputs>(): T {
+    return this.inputs as T;
   }
 
-  private _readOptionValue(opt: CliOption): boolean | number | string | string[] | unknown | undefined {
-    if (opt.kind === CliOptionKind.Presence) {
-      return this.hasFlag(opt.name);
-    }
-    if (opt.kind === CliOptionKind.Number) {
-      const n = this.numberOpt(opt.name);
-      return n === null ? undefined : n;
-    }
-    if (opt.kind === CliOptionKind.Json) {
-      const raw = this.stringOpt(opt.name);
-      if (raw === undefined) return undefined;
-      try {
-        return JSON.parse(raw) as unknown;
-      } catch {
-        return undefined;
-      }
-    }
-    if (opt.format === CliValueFormat.Duration) {
-      return this.durationOpt(opt.name);
-    }
-    if (opt.format === CliValueFormat.CommaList) {
-      return this.commaListOpt(opt.name);
-    }
-    if (opt.format === CliValueFormat.Date) {
-      return this.dateOpt(opt.name);
-    }
-    if (opt.format === CliValueFormat.DateTime) {
-      return this.dateTimeOpt(opt.name);
-    }
-    return this.stringOpt(opt.name);
+  /**
+   * @deprecated Use {@link inputs} or {@link inputsAs}.
+   */
+  readLeafInputs(): CliLeafInputs {
+    return this.inputs;
+  }
+
+  /**
+   * @deprecated Use sync {@link readLeafInputs} — stdin is preloaded before the handler runs.
+   */
+  readLeafInputsAsync(): Promise<CliLeafInputs> {
+    return Promise.resolve(this.readLeafInputs());
   }
 
   private _leafNode(): CliLeaf | undefined {

package/src/help.ts

@@ -16,6 +16,7 @@ import {
   type CliRouter,
   isCliLeaf,
   isCliRouter,
+  isJsonLeaf,
 } from "./types.ts";
 
 // ── ANSI Style Helpers ────────────────────────────────────────────────────────
@@ -328,6 +329,7 @@ function usageLines(
   helpPath: string[],
   hasCommands: boolean,
   hasArgs: boolean,
+  jsonLeaf: boolean,
   color: boolean,
 ): string[] {
   let fullPath = appName;
@@ -337,6 +339,7 @@ function usageLines(
   const usageOpts = color ? style.aquaBold("[OPTIONS]") : "[OPTIONS]";
   const usageCmd = color ? style.aquaBold("COMMAND") : "COMMAND";
   const usageArgs = color ? style.aquaBold("[ARGS]...") : "[ARGS]...";
+  const usageJson = color ? style.aquaBold("[JSON]") : "[JSON]";
 
   const out: string[] = [];
   if (helpPath.length === 0) {
@@ -347,6 +350,10 @@ function usageLines(
     }
     return out;
   }
+  if (jsonLeaf) {
+    out.push(`${fullPath} ${usageJson}`);
+    return out;
+  }
   out.push(`${fullPath} ${usageOpts}${hasArgs ? ` ${usageArgs}` : ""}`);
   if (hasCommands) {
     out.push(`${fullPath} ${usageCmd} ${usageArgs}`);
@@ -354,6 +361,25 @@ function usageLines(
   return out;
 }
 
+/** Table rows for `kind: "json"` leaf input (schema properties + stdin hint). */
+function rowsForJsonInput(inputSchema: Record<string, unknown> | undefined): HelpRow[] {
+  const hint = "Pass a JSON document as an argument or pipe to stdin.";
+  const rows: HelpRow[] = [{ label: "JSON", description: hint }];
+  const props = inputSchema?.properties;
+  if (!props || typeof props !== "object" || Array.isArray(props)) {
+    return rows;
+  }
+  const required = new Set(Array.isArray(inputSchema?.required) ? inputSchema.required.map((k) => String(k)) : []);
+  for (const [name, prop] of Object.entries(props as Record<string, { description?: string }>)) {
+    const desc = prop.description ?? "";
+    rows.push({
+      label: name,
+      description: required.has(name) ? `(required) ${desc}` : desc,
+    });
+  }
+  return rows;
+}
+
 /** Table rows for named options, including synthetic built-in rows. */
 function rowsForOptions(defs: CliOption[], color: boolean): HelpRow[] {
   const rows: HelpRow[] = [];
@@ -407,7 +433,7 @@ export function cliHelpRender(schema: CliRouter, helpPath: string[], _useStderr:
     lines.push(
       renderTextBox(
         "Usage",
-        usageLines(schema.key, helpPath, (schema.commands ?? []).length > 0, false, color),
+        usageLines(schema.key, helpPath, (schema.commands ?? []).length > 0, false, false, color),
         hw,
         color,
       ).join("\n"),
@@ -446,6 +472,7 @@ export function cliHelpRender(schema: CliRouter, helpPath: string[], _useStderr:
     lines.push(color ? style.white(node.description) : node.description);
     lines.push("");
   }
+  const nodeIsJsonLeaf = isCliLeaf(node) && isJsonLeaf(node);
   lines.push(
     renderTextBox(
       "Usage",
@@ -454,6 +481,7 @@ export function cliHelpRender(schema: CliRouter, helpPath: string[], _useStderr:
         helpPath,
         isCliRouter(node) && node.commands.length > 0,
         isCliLeaf(node) && (node.positionals ?? []).length > 0,
+        nodeIsJsonLeaf,
         color,
       ),
       hw,
@@ -461,21 +489,29 @@ export function cliHelpRender(schema: CliRouter, helpPath: string[], _useStderr:
     ).join("\n"),
   );
 
-  const optBox = renderTableBox("Options", rowsForOptions(visibleOptions(node.options), color), hw, color);
-  if (optBox.length > 0) {
-    lines.push("");
-    lines.push(optBox.join("\n"));
-  }
+  if (nodeIsJsonLeaf && isCliLeaf(node)) {
+    const inputBox = renderTableBox("Input", rowsForJsonInput(node.inputSchema), hw, color);
+    if (inputBox.length > 0) {
+      lines.push("");
+      lines.push(inputBox.join("\n"));
+    }
+  } else {
+    const optBox = renderTableBox("Options", rowsForOptions(visibleOptions(node.options), color), hw, color);
+    if (optBox.length > 0) {
+      lines.push("");
+      lines.push(optBox.join("\n"));
+    }
 
-  const posBox = renderTableBox(
-    "Arguments",
-    rowsForPositionals(isCliLeaf(node) ? (node.positionals ?? []) : [], color),
-    hw,
-    color,
-  );
-  if (posBox.length > 0) {
-    lines.push("");
-    lines.push(posBox.join("\n"));
+    const posBox = renderTableBox(
+      "Arguments",
+      rowsForPositionals(isCliLeaf(node) ? (node.positionals ?? []) : [], color),
+      hw,
+      color,
+    );
+    if (posBox.length > 0) {
+      lines.push("");
+      lines.push(posBox.join("\n"));
+    }
   }
 
   const subcmds = isCliRouter(node) ? node.commands : [];