argsbarg 6.1.1 → 6.1.2

package/CHANGELOG.md

@@ -7,6 +7,12 @@ 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
@@ -764,7 +770,8 @@ 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.1...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

package/docs/cli-program.md

@@ -255,6 +255,30 @@ Use **`ctx.jsonOpt("invoice")`**, **`ctx.inputs`**, or **`ctx.inputsAs<MyInput>(
 
 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/index.d.ts

@@ -490,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. */
@@ -545,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.
@@ -672,7 +681,7 @@ export declare function readJsonOptionValue(ctx: CliContext, name: string): unkn
  * 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): Promise<Record<string, unknown>>;
+export declare function preloadPipableJson(program: CliProgram, commandPath: string[], opts: Record<string, string>, invocation: CliInvocation, args?: string[]): Promise<Record<string, unknown>>;
 /**
  * Loads coerced leaf inputs and validates against `leaf.inputSchema` when set.
  * Used by {@link CliContext.inputs}; prefer `ctx.inputs` or `ctx.inputsAs()` in handlers.

package/package.json

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

package/src/cli.ts

@@ -127,7 +127,7 @@ export class Cli {
 
     let preloadedJson: Record<string, unknown> = {};
     try {
-      preloadedJson = await preloadPipableJson(this.program, pr.path, pr.opts, "cli");
+      preloadedJson = await preloadPipableJson(this.program, pr.path, pr.opts, "cli", pr.args);
     } catch (err) {
       if (err instanceof LeafInputError) {
         this.exitLeafInputError(err, pr.path);

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 : [];

package/src/index.ts

@@ -51,6 +51,7 @@ export type {
   CliDocsTopic,
   CliHandler,
   CliInvocation,
+  CliLeafKind,
   CliMcpBundleConfig,
   CliMcpResource,
   CliMcpServerConfig,
@@ -69,5 +70,6 @@ export {
   CliOptionKind,
   CliSchemaValidationError,
   CliValueFormat,
+  isJsonLeaf,
 } from "./types.ts";
 export { isInteractiveTty } from "./utils.ts";

package/src/json-leaf.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, test } from "bun:test";
+import { Cli } from "./index.ts";
+import { ParseKind, parse } from "./parse.ts";
+import { CliOptionKind, type CliProgram, CliSchemaValidationError } from "./types.ts";
+import { cliValidateProgram } from "./validate.ts";
+
+const bodySchema = {
+  type: "object",
+  properties: {
+    format: { type: "string", enum: ["pdf", "html"] },
+    invoice: {
+      type: "object",
+      properties: { id: { type: "string" } },
+      required: ["id"],
+      additionalProperties: false,
+    },
+  },
+  required: ["format", "invoice"],
+  additionalProperties: false,
+} as const;
+
+function jsonLeafProgram() {
+  return {
+    key: "json-leaf-test",
+    version: "1.0.0",
+    description: "json leaf tests",
+    commands: [
+      {
+        key: "render",
+        description: "Render from JSON body",
+        kind: "json",
+        inputSchema: bodySchema,
+        handler: (ctx) => ctx.inputsAs<{ format: string; invoice: { id: string } }>(),
+      },
+    ],
+  } satisfies CliProgram;
+}
+
+describe("kind: json leaf", () => {
+  test("validate requires inputSchema and forbids options/positionals", () => {
+    expect(() =>
+      cliValidateProgram({
+        key: "bad",
+        version: "1",
+        description: "bad",
+        commands: [{ key: "x", description: "x", kind: "json", handler: () => {} }],
+      }),
+    ).toThrow(CliSchemaValidationError);
+
+    expect(() =>
+      cliValidateProgram({
+        key: "bad",
+        version: "1",
+        description: "bad",
+        commands: [
+          {
+            key: "x",
+            description: "x",
+            kind: "json",
+            inputSchema: bodySchema,
+            options: [{ name: "f", description: "f", kind: CliOptionKind.String }],
+            handler: () => {},
+          },
+        ],
+      }),
+    ).toThrow(CliSchemaValidationError);
+
+    expect(() =>
+      cliValidateProgram({
+        key: "bad",
+        version: "1",
+        description: "bad",
+        commands: [
+          {
+            key: "x",
+            description: "x",
+            kind: "json",
+            inputSchema: bodySchema,
+            positionals: [{ name: "file", description: "file", kind: CliOptionKind.String }],
+            handler: () => {},
+          },
+        ],
+      }),
+    ).toThrow(CliSchemaValidationError);
+  });
+
+  test("parse rejects CLI flags on json leaf", () => {
+    const root = jsonLeafProgram();
+    const pr = parse(root, ["render", "--format", "pdf"]);
+    expect(pr.kind).toBe(ParseKind.Error);
+    expect(pr.errorMsg).toContain("JSON commands do not accept options");
+  });
+
+  test("parse accepts JSON positional", () => {
+    const root = jsonLeafProgram();
+    const pr = parse(root, ["render", '{"format":"pdf","invoice":{"id":"1"}}']);
+    expect(pr.kind).toBe(ParseKind.Ok);
+    expect(pr.args).toEqual(['{"format":"pdf","invoice":{"id":"1"}}']);
+  });
+
+  test("invoke reads body from toolArgs", async () => {
+    const cli = new Cli(jsonLeafProgram());
+    const result = await cli.invoke(["render"], {
+      invocation: "api",
+      toolArgs: { format: "pdf", invoice: { id: "INV-1" } },
+    });
+    expect(result.kind).toBe("ok");
+    expect(result.response?.body).toEqual({ format: "pdf", invoice: { id: "INV-1" } });
+  });
+
+  test("invoke reads body from JSON positional argv", async () => {
+    const cli = new Cli(jsonLeafProgram());
+    const result = await cli.invoke(["render", '{"format":"html","invoice":{"id":"2"}}'], {
+      invocation: "mcp",
+    });
+    expect(result.kind).toBe("ok");
+    expect(result.response?.body).toEqual({ format: "html", invoice: { id: "2" } });
+  });
+
+  test("invoke errors when body missing", async () => {
+    const cli = new Cli(jsonLeafProgram());
+    const result = await cli.invoke(["render"], { invocation: "api" });
+    expect(result.kind).toBe("error");
+    expect(result.errorMsg).toContain("Missing JSON input");
+  });
+
+  test("invoke validates inputSchema before handler", async () => {
+    let called = false;
+    const base = jsonLeafProgram();
+    const program = {
+      ...base,
+      commands: [
+        {
+          ...base.commands[0],
+          handler: () => {
+            called = true;
+          },
+        },
+      ],
+    } satisfies CliProgram;
+    const cli = new Cli(program);
+    const result = await cli.invoke(["render"], {
+      invocation: "api",
+      toolArgs: { format: "pdf", invoice: { id: 123 } },
+    });
+    expect(result.kind).toBe("error");
+    expect(called).toBe(false);
+  });
+
+  test("non-object JSON body returns error", async () => {
+    const cli = new Cli(jsonLeafProgram());
+    const result = await cli.invoke(["render", '"not-an-object"'], { invocation: "cli" });
+    expect(result.kind).toBe("error");
+    expect(result.errorMsg).toContain("JSON input must be a JSON object");
+  });
+});

package/src/leaf-inputs.ts

@@ -6,7 +6,7 @@ import { validateConfigDocument } from "./config/validate.ts";
 import type { CliContext, CliLeafInputs } from "./context.ts";
 import { collectOptionDefs } from "./parse.ts";
 import type { CliInvocation, CliLeaf, CliNode, CliOption, CliProgram } from "./types.ts";
-import { CliOptionKind, CliValueFormat, isCliLeaf, isCliRouter } from "./types.ts";
+import { CliOptionKind, CliValueFormat, isCliLeaf, isCliRouter, isJsonLeaf } from "./types.ts";
 import { isInteractiveTty } from "./utils.ts";
 
 /** Thrown when leaf input resolution or validation fails. */
@@ -17,9 +17,12 @@ export class LeafInputError extends Error {
   }
 }
 
-function leafNode(ctx: CliContext): CliLeaf | undefined {
-  let node: CliNode = ctx.program;
-  for (const seg of ctx.commandPath) {
+/** Internal key for piped stdin on `kind: "json"` leaves. */
+export const JSON_LEAF_BODY_KEY = "__jsonLeafBody";
+
+function resolveLeaf(program: CliProgram, commandPath: string[]): CliLeaf | undefined {
+  let node: CliNode = program;
+  for (const seg of commandPath) {
     if (!isCliRouter(node)) return undefined;
     const child = node.commands.find((c) => c.key === seg);
     if (!child) return undefined;
@@ -28,6 +31,10 @@ function leafNode(ctx: CliContext): CliLeaf | undefined {
   return isCliLeaf(node) ? node : undefined;
 }
 
+function leafNode(ctx: CliContext): CliLeaf | undefined {
+  return resolveLeaf(ctx.program, ctx.commandPath);
+}
+
 /** Parses a JSON string from a `--name` flag value. */
 export function parseJsonText(raw: string, label: string): unknown {
   const trimmed = raw.trim();
@@ -54,6 +61,23 @@ async function readPipedJsonStdin(): Promise<unknown> {
   }
 }
 
+function jsonLeafBodyHelp(): string {
+  return "Missing JSON input: pass a JSON document as an argument or pipe to stdin";
+}
+
+async function readPipedJsonStdinForJsonLeaf(): Promise<unknown> {
+  const raw = await new Response(Bun.stdin).text();
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    throw new LeafInputError(jsonLeafBodyHelp());
+  }
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    throw new LeafInputError("stdin is not valid JSON");
+  }
+}
+
 function pipableJsonHelp(opt: CliOption): string {
   return `Missing required option --${opt.name}: pass JSON via --${opt.name} '<json>' or pipe a JSON document to stdin`;
 }
@@ -99,10 +123,17 @@ export async function preloadPipableJson(
   commandPath: string[],
   opts: Record<string, string>,
   invocation: CliInvocation,
+  args: string[] = [],
 ): Promise<Record<string, unknown>> {
   if (invocation !== "cli" || isInteractiveTty) {
     return {};
   }
+
+  const leaf = resolveLeaf(program, commandPath);
+  if (leaf && isJsonLeaf(leaf) && args.length === 0) {
+    return { [JSON_LEAF_BODY_KEY]: await readPipedJsonStdinForJsonLeaf() };
+  }
+
   for (const opt of collectOptionDefs(program, commandPath)) {
     if (opt.kind === CliOptionKind.Json && opt.pipable && !(opt.name in opts)) {
       return { [opt.name]: await readPipedJsonStdin() };
@@ -150,6 +181,31 @@ export function loadLeafInputs(ctx: CliContext): CliLeafInputs {
   const leaf = leafNode(ctx);
   if (!leaf) return {};
 
+  if (isJsonLeaf(leaf)) {
+    let body: unknown;
+    if (ctx.toolArgs !== undefined) {
+      body = ctx.toolArgs;
+    } else if (ctx.args.length > 0) {
+      const [arg0] = ctx.args;
+      if (arg0 === undefined) {
+        throw new LeafInputError(jsonLeafBodyHelp());
+      }
+      body = parseJsonText(arg0, "JSON argument");
+    } else if (JSON_LEAF_BODY_KEY in ctx.preloadedJson) {
+      body = ctx.preloadedJson[JSON_LEAF_BODY_KEY];
+    } else {
+      throw new LeafInputError(jsonLeafBodyHelp());
+    }
+    if (typeof body !== "object" || body === null || Array.isArray(body)) {
+      throw new LeafInputError("JSON input must be a JSON object");
+    }
+    const out = body as CliLeafInputs;
+    if (leaf.inputSchema !== undefined) {
+      validateAgainstInputSchema(out, leaf.inputSchema);
+    }
+    return omitUndefinedInputs(out);
+  }
+
   const out: CliLeafInputs = {};
   const options = collectOptionDefs(ctx.program, ctx.commandPath);
 

package/src/mcp/tools.ts

@@ -17,6 +17,7 @@ import {
   type CliProgram,
   CliValueFormat,
   isCliLeaf,
+  isJsonLeaf,
   leafOutputSchema,
 } from "../types.ts";
 
@@ -150,6 +151,10 @@ function positionalProperty(p: CliPositional): Record<string, unknown> {
 
 /** Builds inputSchema for a leaf command. */
 function buildInputSchema(root: CliProgram, path: string[], leaf: CliLeaf): Record<string, unknown> {
+  if (isJsonLeaf(leaf) && leaf.inputSchema !== undefined) {
+    return leaf.inputSchema;
+  }
+
   const properties: Record<string, unknown> = {};
   const required: string[] = [];
 
@@ -286,6 +291,10 @@ export function mcpToolCallToArgv(
   tool: McpToolDef,
   args: Record<string, unknown>,
 ): string[] | { error: string } {
+  if (isJsonLeaf(tool.leaf)) {
+    return [...tool.path];
+  }
+
   const argv = [...tool.path];
 
   for (const opt of collectOptionDefs(root, tool.path)) {

package/src/parse.ts

@@ -16,6 +16,7 @@ import {
   CliOptionKind,
   isCliLeaf,
   isCliRouter,
+  isJsonLeaf,
 } from "./types.ts";
 import { fullStringIsDouble } from "./utils.ts";
 
@@ -237,6 +238,48 @@ export function collectOptionDefs(root: CliNode, path: string[]): CliOption[] {
   return defs;
 }
 
+/** Fills `args` for a json leaf from `startIdx` (0 or 1 JSON string positional). */
+function finishJsonLeaf(
+  _node: CliLeaf,
+  startIdx: number,
+  argv: string[],
+  path: string[],
+  opts: Record<string, string>,
+): ParseResult {
+  let idx = startIdx;
+  const args: string[] = [];
+
+  if (idx < argv.length) {
+    const tok = argv[idx];
+    if (isHelpTok(tok)) {
+      return helpResult(path, true);
+    }
+    if (tok === "--") {
+      return errorResult("Unexpected extra arguments", path, []);
+    }
+    if (tok.startsWith("-")) {
+      return errorResult(`JSON commands do not accept options: ${tok}`, path, []);
+    }
+    args.push(tok);
+    idx += 1;
+  }
+
+  if (idx < argv.length) {
+    return errorResult("Unexpected extra arguments", path, []);
+  }
+
+  return {
+    kind: ParseKind.Ok,
+    path,
+    opts,
+    args,
+    helpExplicit: false,
+    helpPath: [],
+    errorMsg: "",
+    errorHelpPath: [],
+  };
+}
+
 /** Fills `args` for a leaf from `startIdx` according to `node.positionals`. */
 function finishLeaf(
   node: CliLeaf,
@@ -412,6 +455,9 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
   let node: CliNode | undefined;
 
   if (isCliLeaf(root)) {
+    if (isJsonLeaf(root)) {
+      return finishJsonLeaf(root, i, argv, path, opts);
+    }
     return finishLeaf(root, i, argv, path, opts, root.options ?? [], forcePositionals);
   }
 
@@ -473,6 +519,10 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
 
   // Walk the command tree
   while (true) {
+    if (isCliLeaf(current) && isJsonLeaf(current)) {
+      return finishJsonLeaf(current, i, argv, path, opts);
+    }
+
     if (!forcePositionals) {
       const orep = consumeOptions(collectOptionDefs(root, path), false, argv, i, opts);
       if (orep.report.err) {

package/src/types.ts

@@ -418,10 +418,18 @@ export interface CliNodeBase {
   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. */
@@ -482,6 +490,11 @@ export function isCliLeaf(node: CliNode): node is CliLeaf {
   return "handler" in node && typeof node.handler === "function";
 }
 
+/** True when the leaf accepts a pure JSON body (no CLI flags). */
+export function isJsonLeaf(leaf: CliLeaf): boolean {
+  return leaf.kind === "json";
+}
+
 /** True when the node is a router (has subcommands). */
 export function isCliRouter(node: CliNode): node is CliRouter {
   return "commands" in node && Array.isArray(node.commands);

package/src/validate.ts

@@ -19,6 +19,7 @@ import {
   type InstallTargetSpec,
   isCliLeaf,
   isCliRouter,
+  isJsonLeaf,
 } from "./types.ts";
 
 /** Validates `docs` configuration on the program root. */
@@ -238,6 +239,17 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
     if (isRoot && node.mcpTool !== undefined) {
       throw new CliSchemaValidationError("mcpTool is only supported on leaf commands");
     }
+    if (isJsonLeaf(node)) {
+      if (node.inputSchema === undefined) {
+        throw new CliSchemaValidationError(`kind: "json" requires inputSchema on ${node.key}`);
+      }
+      if ((node.options ?? []).length > 0) {
+        throw new CliSchemaValidationError(`kind: "json" forbids options on ${node.key}`);
+      }
+      if ((node.positionals ?? []).length > 0) {
+        throw new CliSchemaValidationError(`kind: "json" forbids positionals on ${node.key}`);
+      }
+    }
     const outputSchema = node.outputSchema;
     const legacyOutputSchema = node.mcpTool?.outputSchema;
     if (outputSchema !== undefined && legacyOutputSchema !== undefined) {