argsbarg 7.0.7 → 7.0.9

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **Non-TTY in-band schema discovery in `--help`** — when `--help` is invoked in non-TTY environments (such as pipes, scripts, and AI agent subprocesses), argsbarg automatically outputs full, untruncated YAML `Output Schema` (and `Input Schema` on `kind: "json"` commands) below command options and arguments. Enables zero-drift contract discovery for AI agents in a single turn without reading external documentation.
+- **Unboxed plain-text help in non-TTY** — strips Unicode box borders, vertical bars, and trailing whitespace padding when output is not a TTY, outputting clean, indented plain text that optimizes token usage and prevents parsing artifacts in automated tooling. TTY sessions retain compact, rounded UTF-8 boxes without schema bloat by default.
+- **`schemaToYamlLines` helper** — exported utility converting JSON Schema definitions (with `$ref` resolution, property JSDoc comments, optional `?` markers, and enums) into clean, human- and agent-readable YAML representation.
+
 ## [7.0.7] - 2026-09-15
 
 ### Removed
@@ -984,7 +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.7...HEAD
+[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/README.md

@@ -148,7 +148,7 @@ ArgsBarg automatically integrates several core features into your application. T
 
 ### Core Capabilities (Stable)
 
-- `-h` / `--help` — Highly-formatted, terminal-width scoped help at any routing depth.
+- `-h` / `--help` — Highly-formatted, terminal-width scoped help at any routing depth. Rounded UTF-8 boxes in TTY; unboxed plain text with in-band YAML input and output schemas in non-TTY for zero-drift agent discovery.
 - `version` — Print the program's version (e.g., `myapp version`).
 - `http` — Launch the high-performance HTTP REST server (injected when `httpServer.enabled` is `true`).
 - `completion bash` / `zsh` / `fish` — Generate shell completion scripts to stdout for deployment and packaging.

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/docs/output-schema.md

@@ -23,6 +23,7 @@ export const status = {
 | `myapp docs cli` | Markdown per-command **Output** section |
 | MCP `tools/list` | Optional `outputSchema` on each tool |
 | HTTP `GET /openapi.json` | Response schema per tool |
+| CLI `--help` (non-TTY) | YAML output schema for zero-drift in-band agent discovery |
 
 **Not validated at runtime** — argsbarg does not parse or reject handler stdout against the schema today. The schema is documentation and MCP/HTTP metadata.
 

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.7",
+  "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;