argsbarg 7.0.8 → 7.0.9

package/CHANGELOG.md

@@ -7,7 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [7.0.8] - 2026-09-15
+## [7.0.9] - 2026-09-16
+
+### Added
+
+- **`kind: "document"` leaf commands with YAML and JSON support** — introduced `kind: "document"` as the primary naming for structured payload leaves, while retaining `kind: "json"` and `isJsonLeaf` as fully backward-compatible aliases. Both `"document"` and `"json"` leaves now accept YAML input in addition to JSON via command positional arguments and piped stdin.
+- **YAML request body support in HTTP server** — the HTTP API server now accepts YAML request bodies in addition to JSON for structured document endpoints.
+- **`isDocumentLeaf` and `parseDocumentText` exports** — exported `isDocumentLeaf` type guard and `parseDocumentText` utility from framework root and CLI exports.
+
+### Changed
+
+- **Help rendering for document leaves** — usage lines for `kind: "document"` leaves render `[DOCUMENT]` (retaining `[JSON]` for legacy `kind: "json"` leaves) and describe inputs as `"Pass a JSON or YAML document as an argument or pipe to stdin."`
 
 ### Added
 
@@ -992,8 +1002,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/v7.0.8...HEAD
-[7.0.8]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.8
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v7.0.9...HEAD
+[7.0.9]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.9
 [7.0.7]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.7
 [7.0.6]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.6
 [7.0.5]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.5

package/docs/cli-program.md

@@ -108,7 +108,7 @@ Use root **`notes`** for cross-cutting hints shown in help (install commands, do
 Descriptions and schemas are copied into MCP tools and HTTP OpenAPI — optimize for smaller, clearer agent payloads:
 
 - **Declare options on the leaf command** that uses them — routing groups cannot declare options (program root may). Wire schemas (MCP, OpenAPI) expose leaf-local options only.
-- Prefer **`kind: "json"`** leaves with schemagen `inputSchema` for complex tool bodies (one nested object beats many flat flags).
+- Prefer **`kind: "document"`** (or legacy `kind: "json"`) leaves with schemagen `inputSchema` for complex tool bodies (one nested object beats many flat flags).
 - Keep **`description`** strings short and action-oriented; put examples in **`notes`**, not duplicated in every option.
 - Use **`hidden: true`** or **`mcpTool.enabled: false`** for debug/internal commands.
 - For shape discovery: HTTP agents load **`docs openapi`** or `GET /openapi.json`; MCP agents use **`docs cli-schema`**; load full **`docs cli`** only when prose is needed.
@@ -300,15 +300,15 @@ 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"`)
+### Structured document leaves (`kind: "document"`)
 
-When the entire tool body is JSON (no CLI flags), set **`kind: "json"`** on the leaf with **`inputSchema`** and **no `options` or `positionals`**:
+When the entire tool body is a structured document (JSON or YAML, no CLI flags), set **`kind: "document"`** (or legacy `"json"`) on the leaf with **`inputSchema`** and **no `options` or `positionals`**:
 
 ```typescript
 {
   key: "render-invoice",
   description: "Render an invoice from template data",
-  kind: "json",
+  kind: "document",
   inputSchema,
   handler: (ctx) => {
     const { format, invoice } = ctx.inputsAs<RenderInvoiceInput>();
@@ -319,10 +319,25 @@ When the entire tool body is JSON (no CLI flags), set **`kind: "json"`** on the
 
 | 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) |
+| CLI | One JSON or YAML positional **or** pipe a JSON/YAML document to stdin |
+| MCP / HTTP | Full tool args object (`ctx.toolArgs` / JSON or YAML request body) |
 
-Example CLI: `jq '{format:"pdf", invoice:.}' data.json | myapp render-invoice`
+Example CLI:
+```bash
+# JSON positional or pipe
+jq '{format:"pdf", invoice:.}' data.json | myapp render-invoice
+myapp render-invoice '{"format":"pdf","invoice":{"id":"INV-1"}}'
+
+# YAML positional or pipe
+myapp render-invoice 'format: pdf
+invoice:
+  id: INV-1'
+cat << 'EOF' | myapp render-invoice
+format: pdf
+invoice:
+  id: INV-1
+EOF
+```
 
 See [output-schema.md](output-schema.md) for schemagen `inputType`, [http-server.md](http-server.md) for HTTP tool bodies, and [json-schema-subset.md](json-schema-subset.md) for validation drafts, Zod interop, and keyword notes.
 

package/index.d.ts

@@ -618,15 +618,16 @@ 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";
+/** Leaf input mode: `document` (or legacy `json`) = structured JSON or YAML document body (no CLI flags). */
+export type CliLeafKind = "document" | "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`.
+	 * When `"document"` (or legacy `"json"`), the leaf accepts a single JSON or YAML document
+	 * (CLI positional or piped stdin; MCP/HTTP tool args = body). Requires `inputSchema`;
+	 * forbids `options` and `positionals`.
 	 */
 	kind?: CliLeafKind;
 	/** Handler function for leaf commands. */
@@ -814,8 +815,14 @@ export type CliProgram = CliNode & {
 	/** Program version (printed by the `version` built-in and MCP serverInfo). */
 	version: string;
 };
-/** True when the leaf accepts a pure JSON body (no CLI flags). */
-export declare function isJsonLeaf(leaf: CliLeaf): boolean;
+/** True when the leaf accepts a structured JSON or YAML document body (no CLI flags). */
+export declare function isDocumentLeaf(
+/** Leaf command node to inspect. */
+leaf: CliLeaf): boolean;
+/** True when the leaf accepts a structured document body (backward-compatible alias for `isDocumentLeaf`). */
+export declare function isJsonLeaf(
+/** Leaf command node to inspect. */
+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.
@@ -844,6 +851,12 @@ export declare function parseDateTime(s: string): string;
 export declare class LeafInputError extends Error {
 	constructor(message: string);
 }
+/** Parses a JSON or YAML string from a command argument or document body. */
+export declare function parseDocumentText(
+/** Raw text containing a JSON or YAML document. */
+raw: string, 
+/** Field or argument label for error reporting. */
+label: string): unknown;
 /** Resolves a Json option from argv, preloaded stdin, or toolArgs (flag wins). */
 export declare function readJsonOptionValue(ctx: CliContext, name: string): unknown | undefined;
 /**

package/package.json

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

package/src/core/document-leaf.test.ts

@@ -0,0 +1,208 @@
+/*
+Tests for structured document leaves (kind: "document") supporting JSON and YAML document input.
+*/
+
+import { describe, expect, test } from "bun:test";
+import { Cli } from "../index.ts";
+import { LeafInputError, parseDocumentText } from "./leaf-inputs.ts";
+import { ParseKind, parse } from "./parse.ts";
+import { CliOptionKind, type CliProgram, CliSchemaValidationError } from "./types.ts";
+import { cliValidateProgram } from "./validate.ts";
+
+/** JSON Schema for the deployment test document body. */
+const deploySchema = {
+  type: "object",
+  properties: {
+    target: { type: "string", enum: ["staging", "production"] },
+    config: {
+      type: "object",
+      properties: { replicas: { type: "integer" } },
+      required: ["replicas"],
+      additionalProperties: false,
+    },
+  },
+  required: ["target", "config"],
+  additionalProperties: false,
+} as const;
+
+/** Creates a test program with a single `kind: "document"` leaf command. */
+function documentLeafProgram() {
+  return {
+    key: "document-leaf-test",
+    version: "1.0.0",
+    description: "document leaf tests",
+    commands: [
+      {
+        key: "deploy",
+        description: "Deploy from document body",
+        kind: "document",
+        inputSchema: deploySchema,
+        handler: (ctx) => ctx.inputsAs<{ target: string; config: { replicas: number } }>(),
+      },
+    ],
+  } satisfies CliProgram;
+}
+
+/** Tests for `kind: "document"` leaf commands. */
+describe("kind: document leaf", () => {
+  /** Tests validation rules for document leaves. */
+  test("validate requires inputSchema and forbids options/positionals", () => {
+    expect(() =>
+      cliValidateProgram({
+        key: "bad",
+        version: "1",
+        description: "bad",
+        commands: [{ key: "x", description: "x", kind: "document", handler: () => {} }],
+      }),
+    ).toThrow(CliSchemaValidationError);
+
+    expect(() =>
+      cliValidateProgram({
+        key: "bad",
+        version: "1",
+        description: "bad",
+        commands: [
+          {
+            key: "x",
+            description: "x",
+            kind: "document",
+            inputSchema: deploySchema,
+            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: "document",
+            inputSchema: deploySchema,
+            positionals: [{ name: "file", description: "file", kind: CliOptionKind.String }],
+            handler: () => {},
+          },
+        ],
+      }),
+    ).toThrow(CliSchemaValidationError);
+  });
+
+  /** Tests that flags on document leaves are rejected. */
+  test("parse rejects CLI flags on document leaf", () => {
+    const root = documentLeafProgram();
+    const pr = parse(root, ["deploy", "--target", "staging"]);
+    expect(pr.kind).toBe(ParseKind.Error);
+    expect(pr.errorMsg).toContain("Document commands do not accept options");
+  });
+
+  /** Tests that document leaf accepts positional argument tokens. */
+  test("parse accepts document positional token", () => {
+    const root = documentLeafProgram();
+    const pr = parse(root, ["deploy", "target: staging"]);
+    expect(pr.kind).toBe(ParseKind.Ok);
+    expect(pr.args).toEqual(["target: staging"]);
+  });
+
+  /** Tests reading body from YAML positional argv. */
+  test("invoke reads body from YAML positional argv", async () => {
+    const cli = new Cli(documentLeafProgram());
+    const yaml = "target: staging\nconfig:\n  replicas: 3";
+    const result = await cli.invoke(["deploy", yaml], { invocation: "mcp" });
+    expect(result.kind).toBe("ok");
+    expect(result.response?.body).toEqual({ target: "staging", config: { replicas: 3 } });
+
+    const cliResult = await cli.invoke(["deploy", yaml], { invocation: "cli" });
+    expect(cliResult.kind).toBe("ok");
+    expect(JSON.parse(cliResult.stdout)).toEqual({ target: "staging", config: { replicas: 3 } });
+  });
+
+  /** Tests reading body from JSON positional argv. */
+  test("invoke reads body from JSON positional argv", async () => {
+    const cli = new Cli(documentLeafProgram());
+    const json = '{"target":"production","config":{"replicas":5}}';
+    const result = await cli.invoke(["deploy", json], { invocation: "mcp" });
+    expect(result.kind).toBe("ok");
+    expect(result.response?.body).toEqual({ target: "production", config: { replicas: 5 } });
+  });
+
+  /** Tests reading body from toolArgs. */
+  test("invoke reads body from toolArgs", async () => {
+    const cli = new Cli(documentLeafProgram());
+    const result = await cli.invoke(["deploy"], {
+      invocation: "http",
+      toolArgs: { target: "production", config: { replicas: 10 } },
+    });
+    expect(result.kind).toBe("ok");
+    expect(result.response?.body).toEqual({ target: "production", config: { replicas: 10 } });
+  });
+
+  /** Tests error message when document body is missing. */
+  test("invoke errors when body is missing", async () => {
+    const cli = new Cli(documentLeafProgram());
+    const result = await cli.invoke(["deploy"], { invocation: "cli" });
+    expect(result.kind).toBe("error");
+    expect(result.errorMsg).toContain("Missing document input");
+  });
+
+  /** Tests inputSchema validation error handling. */
+  test("invoke validates inputSchema before handler runs", async () => {
+    let handlerRan = false;
+    const base = documentLeafProgram();
+    const program = {
+      ...base,
+      commands: [
+        {
+          ...base.commands[0],
+          handler: () => {
+            handlerRan = true;
+          },
+        },
+      ],
+    } satisfies CliProgram;
+    const cli = new Cli(program);
+    const result = await cli.invoke(["deploy", "target: invalid-target\nconfig:\n  replicas: 1"], {
+      invocation: "cli",
+    });
+    expect(result.kind).toBe("error");
+    expect(handlerRan).toBe(false);
+  });
+
+  /** Tests non-object document body returns error. */
+  test("non-object document body returns error", async () => {
+    const cli = new Cli(documentLeafProgram());
+    const result = await cli.invoke(["deploy", '"just-a-string"'], { invocation: "cli" });
+    expect(result.kind).toBe("error");
+    expect(result.errorMsg).toContain("Document input must be a JSON or YAML object");
+  });
+});
+
+/** Tests for parseDocumentText helper function. */
+describe("parseDocumentText", () => {
+  /** Tests parsing valid JSON. */
+  test("parses valid JSON object", () => {
+    const parsed = parseDocumentText('{"key":"value"}', "test");
+    expect(parsed).toEqual({ key: "value" });
+  });
+
+  /** Tests parsing valid YAML. */
+  test("parses valid YAML object", () => {
+    const parsed = parseDocumentText("key: value\nnested:\n  count: 2", "test");
+    expect(parsed).toEqual({ key: "value", nested: { count: 2 } });
+  });
+
+  /** Tests empty string throws error. */
+  test("throws on empty string", () => {
+    expect(() => parseDocumentText("   ", "test")).toThrow(LeafInputError);
+  });
+
+  /** Tests invalid syntax throws error. */
+  test("throws on invalid syntax", () => {
+    expect(() => parseDocumentText("{bad json", "test")).toThrow(LeafInputError);
+  });
+});

package/src/core/json-leaf.test.ts

@@ -1,9 +1,14 @@
+/*
+Tests for pure JSON leaves (kind: "json") including backward-compatibility and YAML document input.
+*/
+
 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";
 
+/** JSON Schema for the invoice render test body. */
 const bodySchema = {
   type: "object",
   properties: {
@@ -19,6 +24,7 @@ const bodySchema = {
   additionalProperties: false,
 } as const;
 
+/** Creates a test program with a single `kind: "json"` leaf command. */
 function jsonLeafProgram() {
   return {
     key: "json-leaf-test",
@@ -36,7 +42,9 @@ function jsonLeafProgram() {
   } satisfies CliProgram;
 }
 
+/** Tests for `kind: "json"` leaf commands. */
 describe("kind: json leaf", () => {
+  /** Tests validation rules for json leaves. */
   test("validate requires inputSchema and forbids options/positionals", () => {
     expect(() =>
       cliValidateProgram({
@@ -84,6 +92,7 @@ describe("kind: json leaf", () => {
     ).toThrow(CliSchemaValidationError);
   });
 
+  /** Tests that flags on json leaves are rejected. */
   test("parse rejects CLI flags on json leaf", () => {
     const root = jsonLeafProgram();
     const pr = parse(root, ["render", "--format", "pdf"]);
@@ -91,6 +100,7 @@ describe("kind: json leaf", () => {
     expect(pr.errorMsg).toContain("JSON commands do not accept options");
   });
 
+  /** Tests that json leaf accepts JSON positional arguments. */
   test("parse accepts JSON positional", () => {
     const root = jsonLeafProgram();
     const pr = parse(root, ["render", '{"format":"pdf","invoice":{"id":"1"}}']);
@@ -98,6 +108,7 @@ describe("kind: json leaf", () => {
     expect(pr.args).toEqual(['{"format":"pdf","invoice":{"id":"1"}}']);
   });
 
+  /** Tests reading body from toolArgs. */
   test("invoke reads body from toolArgs", async () => {
     const cli = new Cli(jsonLeafProgram());
     const result = await cli.invoke(["render"], {
@@ -108,6 +119,7 @@ describe("kind: json leaf", () => {
     expect(result.response?.body).toEqual({ format: "pdf", invoice: { id: "INV-1" } });
   });
 
+  /** Tests reading body from JSON positional argv. */
   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"}}'], {
@@ -117,6 +129,18 @@ describe("kind: json leaf", () => {
     expect(result.response?.body).toEqual({ format: "html", invoice: { id: "2" } });
   });
 
+  /** Tests reading body from YAML positional argv for kind: "json" leaf. */
+  test("invoke reads body from YAML positional argv", async () => {
+    const cli = new Cli(jsonLeafProgram());
+    const yamlBody = "format: pdf\ninvoice:\n  id: 'INV-YAML-1'";
+    const result = await cli.invoke(["render", yamlBody], {
+      invocation: "mcp",
+    });
+    expect(result.kind).toBe("ok");
+    expect(result.response?.body).toEqual({ format: "pdf", invoice: { id: "INV-YAML-1" } });
+  });
+
+  /** Tests error when body is missing. */
   test("invoke errors when body missing", async () => {
     const cli = new Cli(jsonLeafProgram());
     const result = await cli.invoke(["render"], { invocation: "http" });
@@ -124,6 +148,7 @@ describe("kind: json leaf", () => {
     expect(result.errorMsg).toContain("Missing JSON input");
   });
 
+  /** Tests inputSchema validation before handler runs. */
   test("invoke validates inputSchema before handler", async () => {
     let called = false;
     const base = jsonLeafProgram();
@@ -147,6 +172,7 @@ describe("kind: json leaf", () => {
     expect(called).toBe(false);
   });
 
+  /** Tests error on non-object JSON body. */
   test("non-object JSON body returns error", async () => {
     const cli = new Cli(jsonLeafProgram());
     const result = await cli.invoke(["render", '"not-an-object"'], { invocation: "cli" });

package/src/core/leaf-inputs.ts

@@ -7,7 +7,7 @@ import { isInteractiveTty } from "../utils.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, isJsonLeaf } from "./types.ts";
+import { type CliLeafKind, CliOptionKind, CliValueFormat, isCliLeaf, isCliRouter, isDocumentLeaf } from "./types.ts";
 
 /** Thrown when leaf input resolution or validation fails. */
 export class LeafInputError extends Error {
@@ -17,8 +17,11 @@ export class LeafInputError extends Error {
   }
 }
 
-/** Internal key for piped stdin on `kind: "json"` leaves. */
-export const JSON_LEAF_BODY_KEY = "__jsonLeafBody";
+/** Internal key for piped stdin on `kind: "document"` or `kind: "json"` leaves. */
+export const DOCUMENT_LEAF_BODY_KEY = "__documentLeafBody";
+
+/** Internal key for piped stdin on `kind: "json"` leaves (backward-compatible alias). */
+export const JSON_LEAF_BODY_KEY = DOCUMENT_LEAF_BODY_KEY;
 
 function resolveLeaf(program: CliProgram, commandPath: string[]): CliLeaf | undefined {
   let node: CliNode = program;
@@ -36,7 +39,12 @@ function leafNode(ctx: CliContext): CliLeaf | undefined {
 }
 
 /** Parses a JSON string from a `--name` flag value. */
-export function parseJsonText(raw: string, label: string): unknown {
+export function parseJsonText(
+  /** Raw text to parse as JSON. */
+  raw: string,
+  /** Field or argument label for error reporting. */
+  label: string,
+): unknown {
   const trimmed = raw.trim();
   if (trimmed.length === 0) {
     throw new LeafInputError(`${label}: JSON value is empty`);
@@ -48,6 +56,31 @@ export function parseJsonText(raw: string, label: string): unknown {
   }
 }
 
+/** Parses a JSON or YAML string from a command argument or document body. */
+export function parseDocumentText(
+  /** Raw text containing a JSON or YAML document. */
+  raw: string,
+  /** Field or argument label for error reporting. */
+  label: string,
+): unknown {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    throw new LeafInputError(`${label}: value is empty`);
+  }
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try {
+      return JSON.parse(trimmed);
+    } catch {
+      // Fall through to YAML if JSON parse fails
+    }
+  }
+  try {
+    return Bun.YAML.parse(trimmed);
+  } catch {
+    throw new LeafInputError(`${label}: invalid JSON or YAML`);
+  }
+}
+
 async function readPipedJsonStdin(): Promise<unknown> {
   const raw = await new Response(Bun.stdin).text();
   const trimmed = raw.trim();
@@ -61,20 +94,38 @@ async function readPipedJsonStdin(): Promise<unknown> {
   }
 }
 
-function jsonLeafBodyHelp(): string {
+/** Returns the error message when document input is missing. */
+function jsonLeafBodyHelp(
+  /** Leaf kind: document or json. */
+  kind: CliLeafKind = "json",
+): string {
+  if (kind === "document") {
+    return "Missing document input: pass a JSON or YAML document as an argument or pipe to stdin";
+  }
   return "Missing JSON input: pass a JSON document as an argument or pipe to stdin";
 }
 
-async function readPipedJsonStdinForJsonLeaf(): Promise<unknown> {
+/** Reads piped stdin for a document or json leaf command. */
+async function readPipedJsonStdinForJsonLeaf(
+  /** Leaf kind: document or json. */
+  kind: CliLeafKind = "json",
+): Promise<unknown> {
   const raw = await new Response(Bun.stdin).text();
   const trimmed = raw.trim();
   if (trimmed.length === 0) {
-    throw new LeafInputError(jsonLeafBodyHelp());
+    throw new LeafInputError(jsonLeafBodyHelp(kind));
+  }
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try {
+      return JSON.parse(trimmed);
+    } catch {
+      // Fall through to YAML
+    }
   }
   try {
-    return JSON.parse(trimmed);
+    return Bun.YAML.parse(trimmed);
   } catch {
-    throw new LeafInputError("stdin is not valid JSON");
+    throw new LeafInputError("stdin is not valid JSON or YAML");
   }
 }
 
@@ -130,8 +181,8 @@ export async function preloadPipableJson(
   }
 
   const leaf = resolveLeaf(program, commandPath);
-  if (leaf && isJsonLeaf(leaf) && args.length === 0) {
-    return { [JSON_LEAF_BODY_KEY]: await readPipedJsonStdinForJsonLeaf() };
+  if (leaf && isDocumentLeaf(leaf) && args.length === 0) {
+    return { [JSON_LEAF_BODY_KEY]: await readPipedJsonStdinForJsonLeaf(leaf.kind) };
   }
 
   for (const opt of collectOptionDefs(program, commandPath)) {
@@ -181,22 +232,26 @@ export function loadLeafInputs(ctx: CliContext): CliLeafInputs {
   const leaf = leafNode(ctx);
   if (!leaf) return {};
 
-  if (isJsonLeaf(leaf)) {
+  if (isDocumentLeaf(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());
+        throw new LeafInputError(jsonLeafBodyHelp(leaf.kind));
       }
-      body = parseJsonText(arg0, "JSON argument");
+      const label = leaf.kind === "document" ? "Document argument" : "JSON argument";
+      body = parseDocumentText(arg0, label);
     } else if (JSON_LEAF_BODY_KEY in ctx.preloadedJson) {
       body = ctx.preloadedJson[JSON_LEAF_BODY_KEY];
     } else {
-      throw new LeafInputError(jsonLeafBodyHelp());
+      throw new LeafInputError(jsonLeafBodyHelp(leaf.kind));
     }
     if (typeof body !== "object" || body === null || Array.isArray(body)) {
+      if (leaf.kind === "document") {
+        throw new LeafInputError("Document input must be a JSON or YAML object");
+      }
       throw new LeafInputError("JSON input must be a JSON object");
     }
     const out = body as CliLeafInputs;

package/src/core/parse.ts

@@ -19,7 +19,7 @@ import {
   type CliRouter,
   isCliLeaf,
   isCliRouter,
-  isJsonLeaf,
+  isDocumentLeaf,
 } from "./types.ts";
 
 // ── Parse Result ──────────────────────────────────────────────────────────────
@@ -292,9 +292,9 @@ export function collectOptionDefs(root: CliNode, path: string[]): CliOption[] {
   return [...(node.options ?? [])];
 }
 
-/** Fills `args` for a json leaf from `startIdx` (0 or 1 JSON string positional). */
+/** Fills `args` for a document / json leaf from `startIdx` (0 or 1 JSON or YAML string positional). */
 function finishJsonLeaf(
-  _node: CliLeaf,
+  node: CliLeaf,
   startIdx: number,
   argv: string[],
   path: string[],
@@ -313,7 +313,8 @@ function finishJsonLeaf(
       return errorResult("Unexpected extra arguments", path, [], pathParams);
     }
     if (tok.startsWith("-")) {
-      return errorResult(`JSON commands do not accept options: ${tok}`, path, [], pathParams);
+      const kindLabel = node.kind === "document" ? "Document" : "JSON";
+      return errorResult(`${kindLabel} commands do not accept options: ${tok}`, path, [], pathParams);
     }
     args.push(tok);
     idx += 1;
@@ -552,7 +553,7 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
   let node: CliNode | undefined;
 
   if (isCliLeaf(root)) {
-    if (isJsonLeaf(root)) {
+    if (isDocumentLeaf(root)) {
       return finishJsonLeaf(root, i, argv, path, opts, pathParams);
     }
     return finishLeaf(root, i, argv, path, opts, root.options ?? [], forcePositionals, pathParams);
@@ -645,7 +646,7 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
 
   // Walk the command tree
   while (true) {
-    if (isCliLeaf(current) && isJsonLeaf(current)) {
+    if (isCliLeaf(current) && isDocumentLeaf(current)) {
       return finishJsonLeaf(current, i, argv, path, opts, pathParams);
     }
 

package/src/core/types.ts

@@ -500,16 +500,17 @@ export interface CliNodeBase {
   options?: CliOption[];
 }
 
-/** Leaf input mode: `json` = pure JSON body (no CLI flags). */
-export type CliLeafKind = "json";
+/** Leaf input mode: `document` (or legacy `json`) = structured JSON or YAML document body (no CLI flags). */
+export type CliLeafKind = "document" | "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`.
+   * When `"document"` (or legacy `"json"`), the leaf accepts a single JSON or YAML document
+   * (CLI positional or piped stdin; MCP/HTTP tool args = body). Requires `inputSchema`;
+   * forbids `options` and `positionals`.
    */
   kind?: CliLeafKind;
   /** Handler function for leaf commands. */
@@ -691,9 +692,20 @@ 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 leaf accepts a structured JSON or YAML document body (no CLI flags). */
+export function isDocumentLeaf(
+  /** Leaf command node to inspect. */
+  leaf: CliLeaf,
+): boolean {
+  return leaf.kind === "document" || leaf.kind === "json";
+}
+
+/** True when the leaf accepts a structured document body (backward-compatible alias for `isDocumentLeaf`). */
+export function isJsonLeaf(
+  /** Leaf command node to inspect. */
+  leaf: CliLeaf,
+): boolean {
+  return isDocumentLeaf(leaf);
 }
 
 /** True when the node is a router (has subcommands). */

package/src/core/validate.ts

@@ -17,7 +17,7 @@ import {
   CliValueFormat,
   isCliLeaf,
   isCliRouter,
-  isJsonLeaf,
+  isDocumentLeaf,
 } from "./types.ts";
 
 /** Validates `docs` configuration on the program root. */
@@ -264,15 +264,16 @@ 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 (isDocumentLeaf(node)) {
+      const kindStr = `kind: "${node.kind ?? "document"}"`;
       if (node.inputSchema === undefined) {
-        throw new CliSchemaValidationError(`kind: "json" requires inputSchema on ${node.key}`);
+        throw new CliSchemaValidationError(`${kindStr} requires inputSchema on ${node.key}`);
       }
       if ((node.options ?? []).length > 0) {
-        throw new CliSchemaValidationError(`kind: "json" forbids options on ${node.key}`);
+        throw new CliSchemaValidationError(`${kindStr} forbids options on ${node.key}`);
       }
       if ((node.positionals ?? []).length > 0) {
-        throw new CliSchemaValidationError(`kind: "json" forbids positionals on ${node.key}`);
+        throw new CliSchemaValidationError(`${kindStr} forbids positionals on ${node.key}`);
       }
     }
     const outputSchema = node.outputSchema;

package/src/exports/cli.ts

@@ -40,6 +40,7 @@ export {
   CliOptionKind,
   CliSchemaValidationError,
   CliValueFormat,
+  isDocumentLeaf,
   isJsonLeaf,
 } from "../core/types.ts";
 export { Cli, type CliInvokeKind, type CliInvokeResult } from "../runtime/cli.ts";

package/src/help.test.ts

@@ -278,6 +278,46 @@ describe("cliHelpRender", () => {
     expect(help).toContain("# Generated ID.");
     expect(help).toContain("id: string");
   });
+
+  /** Tests that document leaf commands render [DOCUMENT] usage and schema sections. */
+  test("document leaf renders [DOCUMENT] usage and schemas in non-TTY mode", () => {
+    const root = testProgram({
+      key: "myapp",
+      version: "1.0.0",
+      description: "Test application.",
+      commands: [
+        {
+          key: "deploy",
+          kind: "document",
+          description: "Deploy from document.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              target: { type: "string", description: "Deployment target." },
+            },
+            required: ["target"],
+          },
+          outputSchema: {
+            type: "object",
+            properties: {
+              url: { type: "string", description: "Deployment URL." },
+            },
+            required: ["url"],
+          },
+          handler: () => {},
+        },
+      ],
+    });
+    const help = cliHelpRender(cliPresentationRoot(root), ["deploy"], false, { isTTY: false });
+    expect(help).toContain("myapp deploy [DOCUMENT]");
+    expect(help).toContain("Pass a JSON or YAML document as an argument or pipe to stdin.");
+    expect(help).toContain("Input Schema:");
+    expect(help).toContain("# Deployment target.");
+    expect(help).toContain("target: string");
+    expect(help).toContain("Output Schema (JSON):");
+    expect(help).toContain("# Deployment URL.");
+    expect(help).toContain("url: string");
+  });
 });
 
 /** Tests for converting JSON Schema to human- and agent-friendly YAML lines. */

package/src/help.ts

@@ -16,7 +16,7 @@ import {
   type CliRouter,
   isCliLeaf,
   isCliRouter,
-  isJsonLeaf,
+  isDocumentLeaf,
 } from "./core/types.ts";
 import { visibleOptions, visibleSubcommands } from "./runtime/exposure.ts";
 
@@ -376,8 +376,9 @@ function usageLines(
   helpPath: string[],
   hasCommands: boolean,
   hasArgs: boolean,
-  jsonLeaf: boolean,
+  documentLeaf: boolean,
   color: boolean,
+  leafKind?: string,
 ): string[] {
   let fullPath = appName;
   for (const seg of helpPath) {
@@ -386,7 +387,8 @@ 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 docTag = leafKind === "document" ? "[DOCUMENT]" : "[JSON]";
+  const usageDoc = color ? style.aquaBold(docTag) : docTag;
 
   const out: string[] = [];
   if (helpPath.length === 0) {
@@ -397,8 +399,8 @@ function usageLines(
     }
     return out;
   }
-  if (jsonLeaf) {
-    out.push(`${fullPath} ${usageJson}`);
+  if (documentLeaf) {
+    out.push(`${fullPath} ${usageDoc}`);
     return out;
   }
   out.push(`${fullPath} ${usageOpts}${hasArgs ? ` ${usageArgs}` : ""}`);
@@ -408,10 +410,11 @@ 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 }];
+/** Table rows for `kind: "document"` / `kind: "json"` leaf input (schema properties + stdin hint). */
+function rowsForJsonInput(inputSchema: Record<string, unknown> | undefined, kind?: string): HelpRow[] {
+  const hint = "Pass a JSON or YAML document as an argument or pipe to stdin.";
+  const label = kind === "document" ? "DOCUMENT" : "JSON";
+  const rows: HelpRow[] = [{ label, description: hint }];
   const props = inputSchema?.properties;
   if (!props || typeof props !== "object" || Array.isArray(props)) {
     return rows;
@@ -763,7 +766,7 @@ export function cliHelpRender(
     if (isCliLeaf(schema as unknown as CliNode) && showSchema) {
       const leaf = schema as unknown as CliLeaf;
       if (leaf.outputSchema !== undefined) {
-        const title = isJsonLeaf(leaf) ? "Output Schema (JSON)" : "Output Schema (with --json)";
+        const title = isDocumentLeaf(leaf) ? "Output Schema (JSON)" : "Output Schema (with --json)";
         const yamlLines = schemaToYamlLines(leaf.outputSchema, 0);
         if (yamlLines.length > 0) {
           lines.push("");
@@ -800,14 +803,15 @@ export function cliHelpRender(
     lines.push(color ? style.white(node.description) : node.description);
     lines.push("");
   }
-  const nodeIsJsonLeaf = isCliLeaf(node) && isJsonLeaf(node);
+  const nodeIsDocumentLeaf = isCliLeaf(node) && isDocumentLeaf(node);
   const usage = usageLines(
     schema.key,
     helpPath,
     isCliRouter(node) && node.commands.length > 0,
     isCliLeaf(node) && (node.positionals ?? []).length > 0,
-    nodeIsJsonLeaf,
+    nodeIsDocumentLeaf,
     color,
+    isCliLeaf(node) ? node.kind : undefined,
   );
   if (isTTY) {
     lines.push(renderTextBox("Usage", usage, hw, color).join("\n"));
@@ -815,8 +819,8 @@ export function cliHelpRender(
     lines.push(renderPlainSection("Usage", usage).join("\n"));
   }
 
-  if (nodeIsJsonLeaf && isCliLeaf(node)) {
-    const inputRows = rowsForJsonInput(node.inputSchema);
+  if (nodeIsDocumentLeaf && isCliLeaf(node)) {
+    const inputRows = rowsForJsonInput(node.inputSchema, node.kind);
     const inputBox = isTTY ? renderTableBox("Input", inputRows, hw, color) : renderPlainTable("Input", inputRows, hw);
     if (inputBox.length > 0) {
       lines.push("");
@@ -860,7 +864,7 @@ export function cliHelpRender(
   }
 
   if (isCliLeaf(node) && node.outputSchema !== undefined && showSchema) {
-    const title = nodeIsJsonLeaf ? "Output Schema (JSON)" : "Output Schema (with --json)";
+    const title = nodeIsDocumentLeaf ? "Output Schema (JSON)" : "Output Schema (with --json)";
     const yamlLines = schemaToYamlLines(node.outputSchema, 0);
     if (yamlLines.length > 0) {
       lines.push("");

package/src/http/openapi.ts

@@ -3,7 +3,7 @@ Hand-built OpenAPI 3.1 document from exposed HTTP REST routes.
 */
 
 import type { CliHttpMethod, CliNode, CliProgram } from "../core/types.ts";
-import { CliOptionKind, isCliLeaf, isJsonLeaf } from "../core/types.ts";
+import { CliOptionKind, isCliLeaf, isDocumentLeaf } from "../core/types.ts";
 import { leafWireOptions } from "../mcp/tools.ts";
 import { collectHttpRoutes, defaultSuccessStatus } from "./routes.ts";
 import { dereferenceJsonSchema } from "./schema-deref.ts";
@@ -253,7 +253,7 @@ export function generateOpenApi(program: CliProgram): Record<string, unknown> {
       ];
     } else {
       op.requestBody = {
-        required: isJsonLeaf(route.leaf),
+        required: isDocumentLeaf(route.leaf),
         content: {
           [JSON_CONTENT_TYPE]: {
             schema: dereferenceJsonSchema(buildInputSchema(program, route)),

package/src/http/routes.ts

@@ -8,7 +8,7 @@ import {
   type CliNode,
   type CliProgram,
   isCliLeaf,
-  isJsonLeaf,
+  isDocumentLeaf,
   CliOptionKind as OptKind,
 } from "../core/types.ts";
 import { formatMcpOptionValue, leafHasYesOption, leafWireOptions } from "../mcp/tools.ts";
@@ -252,7 +252,7 @@ export function httpRequestToArgv(
   }
 
   const leaf = route.leaf;
-  if (isJsonLeaf(leaf)) {
+  if (isDocumentLeaf(leaf)) {
     return argv;
   }
 

package/src/http/server.ts

@@ -175,7 +175,15 @@ export async function handleApiRequest(
           }
           body = parsed as Record<string, unknown>;
         } catch {
-          return finish(apiErrorResponse(400, { error: "Invalid JSON body" }));
+          try {
+            const parsed = Bun.YAML.parse(rawBody);
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+              return finish(apiErrorResponse(400, { error: "Request body must be a JSON object" }));
+            }
+            body = parsed as Record<string, unknown>;
+          } catch {
+            return finish(apiErrorResponse(400, { error: "Invalid JSON body" }));
+          }
         }
       }
     }

package/src/index.ts

@@ -18,6 +18,7 @@ export {
 } from "./core/formats.ts";
 export {
   LeafInputError,
+  parseDocumentText,
   preloadPipableJson,
   readJsonOptionValue,
 } from "./core/leaf-inputs.ts";
@@ -68,6 +69,7 @@ export {
   CliOptionKind,
   CliSchemaValidationError,
   CliValueFormat,
+  isDocumentLeaf,
   isJsonLeaf,
 } from "./core/types.ts";
 export type { HeadlessContext } from "./headless/routing.ts";

package/src/mcp/tools.ts

@@ -13,7 +13,7 @@ import {
   type CliProgram,
   CliValueFormat,
   isCliLeaf,
-  isJsonLeaf,
+  isDocumentLeaf,
   leafOutputSchema,
 } from "../core/types.ts";
 import { docsMcpResources } from "../docs/mcp-resources.ts";
@@ -155,7 +155,7 @@ function positionalProperty(p: CliPositional): Record<string, unknown> {
 
 /** Builds inputSchema for a leaf command. */
 function buildInputSchema(leaf: CliLeaf): Record<string, unknown> {
-  if (isJsonLeaf(leaf) && leaf.inputSchema !== undefined) {
+  if (isDocumentLeaf(leaf) && leaf.inputSchema !== undefined) {
     return leaf.inputSchema;
   }
 
@@ -294,7 +294,7 @@ export function mcpToolCallToArgv(
   tool: McpToolDef,
   args: Record<string, unknown>,
 ): string[] | { error: string } {
-  if (isJsonLeaf(tool.leaf)) {
+  if (isDocumentLeaf(tool.leaf)) {
     return [...tool.path];
   }
 

package/src/test/integration/http.test.ts

@@ -448,6 +448,42 @@ describe("HTTP API routes", () => {
     expect(body).toEqual({ error: "bad input" });
   });
 
+  /** Tests that POST endpoints accept YAML request bodies. */
+  test("POST accepts YAML request body", async () => {
+    const yamlProgram = testProgram({
+      key: "app",
+      description: "Test app",
+      httpServer: { enabled: true },
+      commands: [
+        {
+          key: "create",
+          kind: "document",
+          description: "Create resource",
+          inputSchema: {
+            type: "object",
+            properties: { name: { type: "string" } },
+            required: ["name"],
+          },
+          handler: (ctx: CliContextType) => {
+            return { created: ctx.inputsAs<{ name: string }>().name };
+          },
+        },
+      ],
+    });
+    cliValidateProgram(yamlProgram);
+    const res = await apiRequest(
+      yamlProgram,
+      new Request("http://127.0.0.1/create", {
+        method: "POST",
+        headers: { "content-type": "application/yaml" },
+        body: "name: test-resource",
+      }),
+    );
+    expect(res.status).toBe(201);
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body).toEqual({ created: "test-resource" });
+  });
+
   test("GET /openapi.json lists REST paths", async () => {
     const res = await apiRequest(program, new Request("http://127.0.0.1/openapi.json"));
     expect(res.status).toBe(200);