argsbarg 6.0.2 → 6.1.1

package/CHANGELOG.md

@@ -7,11 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.1.1] - 2026-07-23
+
+### Added
+
+- **`ctx.inputs`** — coerced, pre-validated leaf inputs (getter; preferred over `readLeafInputs()`).
+- **`ctx.inputsAs<T>()`** — `ctx.inputs` cast to a schemagen or app input type (`T` unconstrained; consumer-asserted).
+
+### Changed
+
+- **`leaf.inputSchema` validation** — runs before the leaf handler in `Cli.run()` and `Cli.invoke()` (same JSON Schema subset as `program.appConfig`). `LeafInputError` prints contextual help on CLI. `ctx.inputs` returns the cached, pre-validated result.
+- **`ctx.readLeafInputs()`** — deprecated; use `ctx.inputs` or `ctx.inputsAs()`.
+
+## [6.1.0] - 2026-07-22
+
+### Added
+
+- **`CliOptionKind.Json`** and **`pipable`** — JSON object options with CLI `--name '<json>'` or piped stdin when the flag is omitted (flag wins if set). MCP/API values merge from `toolArgs`.
+- **`ctx.jsonOpt(name)`** — parsed Json option from flag, preloaded stdin, or MCP/API `toolArgs`.
+- **`ctx.readLeafInputs()`** — all coerced inputs; validates against `leaf.inputSchema` when set (stdin preloaded before handler).
+- **`ctx.readLeafInputsAsync()`** — deprecated alias for sync `readLeafInputs()`.
+
+### Changed
+
+- **Schemagen discovery** — role exports (`configType` / `inputType` / `outputType`) live in `src/**/types.ts` instead of thin `schema.ts` manifests.
+
 ## [6.0.2] - 2026-07-22
 
 ### Added
 
-- **`argsbarg schemagen`** — centralized JSON Schema generation from `src/**/schema.ts` into colocated `__generated__/` directories (`configSchema.json`, `inputSchema.json`, `outputSchema.json`, plus `index.ts` re-exports). Removes orphan `__generated__/` trees and stale JSON when schema roots or kinds are removed.
+- **`argsbarg schemagen`** — centralized JSON Schema generation from thin `src/**/schema.ts` manifests into colocated `__generated__/` directories. Follows role aliases (`configType` / `inputType` / `outputType`) to types in sibling modules (typically `types.ts`).
 - **`argsbarg/schemagen`** export — `runSchemagen`, `discoverSchemaRoots`, and naming helpers (`src/cli-tool/schemagen/`).
 
 ### Changed
@@ -739,7 +764,9 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.0.2...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.1.1...HEAD
+[6.1.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.1
+[6.1.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.0
 [6.0.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.0.2
 [6.0.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.0.1
 [6.0.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.0.0

package/README.md

@@ -207,7 +207,11 @@ Add `CliPositional` entries to the command’s `positionals` list (separate from
 - `ctx.durationOpt("timeout")` — duration options (`format: CliValueFormat.Duration`) as milliseconds.
 - `ctx.commaListOpt("services")` — comma-list options as `string[] | undefined`.
 - `ctx.dateOpt("on")` / `ctx.dateTimeOpt("since")` — ISO date / date-time options.
-- `ctx.readLeafInputs()` — coerced option and positional values for the current leaf (schema-driven).
+- `ctx.inputs` — coerced option and positional values for the current leaf; when `inputSchema` is set, validated before the handler runs and cached on `ctx`.
+- `ctx.inputsAs<T>()` — `ctx.inputs` cast to a schemagen or app input type.
+- `ctx.readLeafInputs()` — deprecated; use `ctx.inputs` or `ctx.inputsAs()`.
+- `ctx.jsonOpt(name)` — parsed Json option (flag, preloaded stdin, or MCP/API `toolArgs`).
+- `ctx.readLeafInputsAsync()` — deprecated alias for `readLeafInputs()`.
 - `ctx.typedOpt<T>("custom", parseFn)` — custom parsing for type-safe option resolution.
 - `ctx.args` — positional words in order as `string[]`.
 - `ctx.positional("name")` — named positional lookup; varargs slots return `string[]`, single slots return `string | undefined`.
@@ -267,8 +271,8 @@ To refresh the Cursor rule in an existing consumer: `bun scripts/merge-cli-progr
 | Area                  | Files / wiring                                                                         |
 | --------------------- | -------------------------------------------------------------------------------------- |
 | All builtins          | `completion`, `version`, `configure`, `docs`, `mcp`, `api`, `configure get`/`set`      |
-| `program.appConfig`   | `src/config/schema.ts` → `configSchema` from `__generated__/`                         |
-| `outputSchema`        | `src/commands/status/schema.ts` → `outputSchema` from `__generated__/`                  |
+| `program.appConfig`   | `src/config/types.ts` → `configSchema` from `__generated__/`                         |
+| `outputSchema`        | `src/commands/status/types.ts` → `outputSchema` from `__generated__/`                  |
 | Schemagen             | `just schemagen` → `argsbarg schemagen` (justfile exports `node_modules/.bin` on `PATH`) |
 | Command layout        | `src/commands/<name>/command.ts`; registration in `src/program.ts`                     |
 | MCP doc topics        | `docs.topics` auto-exposed as `<key>://docs/<topic>` resources when docs + MCP enabled |

package/docs/api-server.md

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

package/docs/cli-program.md

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

package/docs/config-schema.md

@@ -142,7 +142,7 @@ Mirror the [output-schema.md](output-schema.md) pattern for config:
 
 ```mermaid
 flowchart LR
-  subgraph types [schema.ts]
+  subgraph types [types.ts]
     Marker["export type configType = AppConfig"]
   end
   subgraph gen [argsbarg schemagen]
@@ -164,14 +164,14 @@ flowchart LR
 | Piece | Convention |
 | --- | --- |
 | Generator | [`ts-json-schema-generator`](https://github.com/vega/ts-json-schema-generator) (bundled with argsbarg) |
-| Discovery | `export type configType = …` in `src/config/schema.ts` (type defined in same file) |
+| Discovery | `export type configType = …` in `src/config/types.ts` |
 | Artifacts | `src/config/__generated__/` — gitignored; run `just schemagen` after clone |
 | Consumer CI | Optional: `ajv` + `ajv-formats` against the same committed JSON (not an argsbarg runtime dep) |
 
 Example:
 
 ```typescript
-// src/config/schema.ts
+// src/config/types.ts
 export interface AppConfig {
   apiToken: string;
 }

package/docs/output-schema.md

@@ -50,13 +50,13 @@ Reference implementations: **sqsp-qa-manager-poc**, **sqsp-workspaces**, **sqsp-
 
 ```mermaid
 flowchart LR
-  subgraph types [schema.ts]
+  subgraph types [types.ts]
     Config["export type configType = AppConfig"]
     Output["export type outputType = StatusJsonOutput"]
     Input["export type inputType = ToolInput (optional)"]
   end
   subgraph gen [argsbarg schemagen]
-    Discover["discover schema.ts roots"]
+    Discover["discover types.ts roots"]
     Gen["ts-json-schema-generator"]
   end
   subgraph artifacts [Gitignored __generated__]
@@ -74,8 +74,8 @@ flowchart LR
 | Piece | Convention |
 | --- | --- |
 | Generator | [`ts-json-schema-generator`](https://github.com/vega/ts-json-schema-generator) (bundled as an argsbarg dependency) |
-| Discovery | Walk `src/**/schema.ts`; generate from `export type outputType = …` / `inputType` / `configType` when the target type is **defined in that file** |
-| Artifacts | `src/**/__generated__/` — gitignored; run schemagen after clone or when `schema.ts` changes |
+| Discovery | Walk `src/**/types.ts` for `export type outputType` / `inputType` / `configType`; generate from the aliased type in the same file |
+| Artifacts | `src/**/__generated__/` — gitignored; run schemagen after clone or when `types.ts` changes |
 | Invocation | `just schemagen` — justfile exports `node_modules/.bin` on `PATH` for local `argsbarg` |
 | tsconfig | `"resolveJsonModule": true` |
 | CI | `just check`: `schemagen` → typecheck (no git diff on generated files) |
@@ -84,12 +84,10 @@ flowchart LR
 
 ### Declaring a schema root
 
-Put schema-facing interfaces in **`schema.ts`** next to the command (or in a shared module when several commands reuse one shape). Export a role alias:
+Put schema-facing interfaces and role exports in **`types.ts`** (or `core/types.ts` for shared shapes):
 
 ```typescript
-// src/commands/status/schema.ts
-import type { WorkspaceStatus } from "./types.ts";
-
+// src/commands/status/types.ts
 /** JSON stdout for `myapp status --json`. */
 export interface StatusJsonOutput {
   workspaces: WorkspaceStatus[];
@@ -99,10 +97,10 @@ export interface StatusJsonOutput {
 export type outputType = StatusJsonOutput;
 ```
 
-```typescript
-// src/ui/runHeadless/schema.ts — shared by many mutating commands
-import type { HeadlessTaskResult } from "./types.ts";
+Handlers and other modules import from the same **`types.ts`** module.
 
+```typescript
+// src/ui/runHeadless/types.ts — shared by many mutating commands
 export interface HeadlessOpResult {
   command: string;
   exitCode: number;
@@ -113,31 +111,35 @@ export type outputType = HeadlessOpResult;
 ```
 
 ```typescript
-// src/commands/render-invoice/schema.ts — custom HTTP/MCP body (pdf-gen)
-export interface RenderInvoiceToolInput {
+// src/commands/render-invoice/types.ts — custom HTTP/MCP body (pdf-gen)
+export interface RenderInvoiceInput {
   format: "pdf" | "html";
   invoice: InvoiceData;
 }
 
-export type inputType = RenderInvoiceToolInput;
-export type outputType = RenderInvoiceWrittenOutput;
+export interface RenderInvoiceOutput {
+  bytes: number;
+}
+
+export type inputType = RenderInvoiceInput;
+export type outputType = RenderInvoiceOutput;
 ```
 
 | Export | Role |
 | --- | --- |
-| `export type configType = AppConfig` | `program.appConfig.jsonSchema` (one per repo, typically `src/config/schema.ts`) |
+| `export type configType = AppConfig` | `program.appConfig.jsonSchema` (one per repo, typically `src/config/types.ts`) |
 | `export type outputType = …` | `leaf.outputSchema` |
 | `export type inputType = …` | `leaf.inputSchema` (only when the tool body is not flat CLI flags) |
 
-**Domain helpers** stay in `types.ts` (or `core/types.ts`). Discovery scans only `schema.ts`. Re-export-only files (`export type outputType = HeadlessOpResult` pointing at another module) are **not** generation roots — generate once from the canonical definition file.
+**Domain helpers** and **role exports** live in `types.ts`. Commands without structured JSON omit role exports. Shared shapes (e.g. `HeadlessOpResult`) are defined once in `types.ts` with a single `outputType`; other commands import `{ outputSchema }` from that module’s `__generated__/index.ts`.
 
-Commands without structured JSON omit `schema.ts`. Shared shapes (e.g. `HeadlessOpResult`) live in one canonical `schema.ts`; other commands import `{ outputSchema }` from that module’s `__generated__/index.ts`.
+For nested MCP/HTTP bodies, add a `kind: Json` option (same name as the `inputType` property) and use `ctx.jsonOpt(...)` or `ctx.readLeafInputs()` — see [cli-program.md](cli-program.md#json-options-and-piped-stdin).
 
 When you do **not** set `inputSchema`, argsbarg builds tool input from CLI `options` + `positionals`.
 
 ### Generated artifacts
 
-Schemagen writes under `__generated__/` beside each `schema.ts`:
+Schemagen writes under `__generated__/` beside each `types.ts` with role exports:
 
 | Kind | Generated file | Exported const (from `__generated__/index.ts`) |
 | --- | --- | --- |
@@ -174,15 +176,15 @@ appConfig: { jsonSchema: configSchema, entries: { … } },
 
 **Goal:** generated schemas match what handlers actually print, with descriptions agents can read in `docs api`.
 
-1. **Schema roots** — `export interface` in `schema.ts`, with `export type outputType = …` (or `inputType` / `configType`).
+1. **Schema roots** — `export interface` in `types.ts`, with `export type outputType = …` (or `inputType` / `configType`).
 2. **Per property** — `/** … */` on every field that should appear in JSON Schema `properties` (including nested named types).
 3. **Unions / enums** — document the alias; generator emits `enum` / `anyOf` with type-level description.
 4. **Formats** — property JSDoc can include `@format date-time` for ISO timestamps; add a smoke test that the generated property has `format: "date-time"`.
-5. **Do not hand-edit** `__generated__/` — change types/JSDoc in `schema.ts`, run `just schemagen`.
+5. **Do not hand-edit** `__generated__/` — change types/JSDoc in `types.ts`, run `just schemagen`.
 
 ### Narrowing when runtime ≠ stdout
 
-When a shared runtime type is **wider** than one command’s JSON, add a **schema-facing** root in `schema.ts`:
+When a shared runtime type is **wider** than one command’s JSON, add a **schema-facing** root in `types.ts`:
 
 ```typescript
 /** JSON stdout for `myapp pr` and `myapp file`. */
@@ -211,7 +213,7 @@ Per consumer repo (optional):
 
 ## Contributor workflow
 
-1. Add or edit schema roots in `src/**/schema.ts` with `outputType` / `inputType` / `configType` and per-field JSDoc.
+1. Add or edit schema roots in `src/**/types.ts` with `outputType` / `inputType` / `configType` and per-field JSDoc.
 2. `just schemagen` — refresh `src/**/__generated__/`.
 3. Import `{ outputSchema }` / `{ inputSchema }` / `{ configSchema }` from the relevant `__generated__/index.ts`.
 4. `just docgen` / `myapp docs api --save` — refresh consumer docs.
@@ -219,7 +221,7 @@ Per consumer repo (optional):
 
 Add a bullet under your app’s `**… conventions:**` block in `.cursor/rules/cli-program.mdc` pointing at `node_modules/argsbarg/docs/output-schema.md`.
 
-**Reference implementation:** [`examples/full-example/`](../examples/full-example/) in this repo — `schema.ts` roots, `__generated__/`, and `status` leaf with `outputSchema`.
+**Reference implementation:** [`examples/full-example/`](../examples/full-example/) in this repo — `types.ts` roots, `__generated__/`, and `status` leaf with `outputSchema`.
 
 ## Out of scope
 

package/examples/full-example/README.md

@@ -9,7 +9,7 @@ From a git checkout at this directory (requires [Homebrew](https://brew.sh), [ju
 ```bash
 brew install just bun
 just setup
-just schemagen   # after changing src/**/schema.ts
+just schemagen   # after changing src/**/types.ts
 just run status --json
 just run docs readme
 ```
@@ -62,13 +62,13 @@ Undo a local dev install: `just uninstall` (formula + agent artifacts; app confi
 
 ## Schemagen roots
 
-| Export in `schema.ts` | Generated artifact | Import on leaf / program |
+| Export in `types.ts` | Generated artifact | Import on leaf / program |
 | --- | --- | --- |
-| `export type configType = …` | `__generated__/configSchema.json` | `{ configSchema }` from `config/__generated__/index.ts` → `program.appConfig.jsonSchema` |
-| `export type outputType = …` | `__generated__/outputSchema.json` | `{ outputSchema }` from `__generated__/index.ts` → `leaf.outputSchema` |
-| `export type inputType = …` | `__generated__/inputSchema.json` | `{ inputSchema }` from `__generated__/index.ts` → `leaf.inputSchema` |
+| `export type configType = …` | `config/__generated__/configSchema.json` | `{ configSchema }` from `config/__generated__/index.ts` |
+| `export type outputType = …` | `__generated__/outputSchema.json` | `{ outputSchema }` from `__generated__/index.ts` |
+| `export type inputType = …` | `__generated__/inputSchema.json` | `{ inputSchema }` from `__generated__/index.ts` |
 
-Discovery walks `src/**/schema.ts` only. Domain helpers stay in sibling `types.ts`. `__generated__/` is gitignored — run `argsbarg schemagen` (via `just schemagen` or `just setup`).
+Type definitions and schemagen role exports live in `types.ts`. Run `argsbarg schemagen` (via `just schemagen` or `just setup`).
 
 ## Consumer docs
 

package/examples/full-example/src/commands/status/types.ts

@@ -1 +1,19 @@
-export type { StatusJsonOutput } from "./schema.ts";
+/** JSON stdout for `full-example status --json`. */
+export interface StatusJsonOutput {
+  /** Resolved AWS region. */
+  defaultRegion?: string;
+  /** Resolved retry count. */
+  maxRetries?: number;
+  /** Whether apiToken is set (value never included). */
+  apiTokenSet: boolean;
+  /** App version from program root. */
+  version: string;
+}
+
+/** Returns status JSON (identity helper for schema generation). */
+export function buildStatusJson(output: StatusJsonOutput): StatusJsonOutput {
+  return output;
+}
+
+/** Schemagen root for leaf outputSchema. */
+export type outputType = StatusJsonOutput;

package/examples/full-example/src/program.ts

@@ -4,10 +4,10 @@ Kitchen-sink CliProgram — every argsbarg builtin enabled; command registration
 
 import type { CliAppConfig, CliAppConfigEntry, CliProgram } from "argsbarg";
 import readmeText from "../README.md" with { type: "text" };
-import { configSchema } from "./config/__generated__/index.ts";
 import { createIdentity } from "../scripts/create-identity.ts";
 import { echoCommand } from "./commands/echo/command.ts";
 import { statusCommand } from "./commands/status/command.ts";
+import { configSchema } from "./config/__generated__/index.ts";
 
 const configEntries = {
   apiToken: {

package/index.d.ts

@@ -45,7 +45,7 @@ declare class AppConfigSnapshot {
 }
 export type AnyAppConfigSnapshot = AppConfigSnapshot | EmptyAppConfigSnapshot;
 /** Coerced leaf inputs keyed by option and positional names. */
-export type CliLeafInputs = Record<string, boolean | number | string | string[] | undefined>;
+export type CliLeafInputs = Record<string, boolean | number | string | string[] | unknown | undefined>;
 /**
  * Values passed to a leaf command handler after parsing: app name, routed path, args, and merged options.
  */
@@ -59,9 +59,12 @@ export declare class CliContext {
 	readonly appConfig: AnyAppConfigSnapshot;
 	/** Original flat tool arguments for API/MCP invocations (when provided). */
 	readonly toolArgs?: Record<string, unknown>;
+	/** Pipable Json option values read from stdin before the handler (CLI only). */
+	readonly preloadedJson: Record<string, unknown>;
 	private response?;
+	private leafInputsCache?;
 	/** Captures the program root, routed path, positional words, and option map for a leaf handler. */
-	constructor(appName: string, commandPath: string[], args: string[], opts: Record<string, string>, program: CliProgram, invocation?: CliInvocation, appConfig?: AnyAppConfigSnapshot, toolArgs?: Record<string, unknown>);
+	constructor(appName: string, commandPath: string[], args: string[], opts: Record<string, string>, program: CliProgram, invocation?: CliInvocation, appConfig?: AnyAppConfigSnapshot, toolArgs?: Record<string, unknown>, preloadedJson?: Record<string, unknown>);
 	/**
 	 * Sets the machine-readable response for API/MCP invocations, or writes to stdout in CLI mode.
 	 * May only be called once per invocation.
@@ -88,11 +91,30 @@ export declare class CliContext {
 	dateOpt(name: string): string | undefined;
 	/** Date-time option as normalized ISO 8601 UTC (post-parse validated). */
 	dateTimeOpt(name: string): string | undefined;
+	/**
+	 * Parsed Json option: `--name '<json>'`, preloaded piped stdin (when `pipable`), or MCP/API toolArgs.
+	 * Flag wins over stdin and toolArgs.
+	 */
+	jsonOpt(name: string): unknown | undefined;
 	/** Returns the value(s) for a named positional slot. Varargs slots return string[]; single slots return string | undefined. */
 	positional(name: string): string | string[] | undefined;
-	/** Reads coerced option and positional values for the current leaf from schema metadata. */
+	/**
+	 * Coerced option and positional values for the current leaf.
+	 * When `leaf.inputSchema` is set, argsbarg validates before the handler runs; this returns the cached result.
+	 */
+	get inputs(): CliLeafInputs;
+	/**
+	 * {@link inputs} cast to a schemagen or app-defined input type (consumer-asserted; not inferred from `inputSchema`).
+	 */
+	inputsAs<T = CliLeafInputs>(): T;
+	/**
+	 * @deprecated Use {@link inputs} or {@link inputsAs}.
+	 */
 	readLeafInputs(): CliLeafInputs;
-	private _readOptionValue;
+	/**
+	 * @deprecated Use sync {@link readLeafInputs} — stdin is preloaded before the handler runs.
+	 */
+	readLeafInputsAsync(): Promise<CliLeafInputs>;
 	private _leafNode;
 	private _posMap;
 	private _positionalMap;
@@ -102,7 +124,7 @@ export declare class CliContext {
  */
 export type CliInvocation = "cli" | "mcp" | "api";
 /**
- * Option kinds: presence (boolean flag), string (free-form text), number (strict double), or enum (fixed choices).
+ * Option kinds: presence (boolean flag), string (free-form text), number (strict double), enum (fixed choices), or json (parsed JSON object/array).
  */
 export declare enum CliOptionKind {
 	/** Boolean flag: no value token (may be implicit `"1"` when set). */
@@ -112,7 +134,9 @@ export declare enum CliOptionKind {
 	/** Strict floating-point value (parsed at validation time). */
 	Number = "number",
 	/** Fixed set of allowed string values. Requires non-empty `choices` on the option. */
-	Enum = "enum"
+	Enum = "enum",
+	/** JSON object or array (parsed from `--name '<json>'`, piped stdin when `pipable`, or MCP/API tool body). */
+	Json = "json"
 }
 /**
  * Named validation/coercion for string options (`format` on `CliOption`).
@@ -176,6 +200,11 @@ export interface CliOption {
 	default?: string;
 	/** Regex pattern for string options. Mutually exclusive with `format`. */
 	pattern?: string;
+	/**
+	 * When `true` on a `Json` option, CLI may omit `--name` and supply JSON via stdin instead.
+	 * If `--name` is set, the flag value wins and stdin is not read.
+	 */
+	pipable?: boolean;
 }
 /**
  * An ordered positional argument slot, listed on leaf `positionals`.
@@ -584,6 +613,8 @@ export declare class Cli {
 	}): Promise<CliInvokeResult>;
 	serveMcp(): Promise<never>;
 	serveApi(): Promise<never>;
+	private ensureValidatedLeafInputs;
+	private exitLeafInputError;
 	private prepareDispatch;
 	private buildAppConfigSnapshot;
 }
@@ -631,6 +662,26 @@ dryRun?: boolean,
 interactive?: boolean): void;
 /** Prefixes a success message when running in dry-run mode. */
 export declare function formatDryRunMessage(message: string, dryRun: boolean): string;
+/** Thrown when leaf input resolution or validation fails. */
+export declare class LeafInputError extends Error {
+	constructor(message: string);
+}
+/** Resolves a Json option from argv, preloaded stdin, or toolArgs (flag wins). */
+export declare function readJsonOptionValue(ctx: CliContext, name: string): unknown | undefined;
+/**
+ * Reads piped stdin for a pipable Json option when the flag is omitted (CLI only).
+ * Call from {@link Cli.run} before constructing the handler context.
+ */
+export declare function preloadPipableJson(program: CliProgram, commandPath: string[], opts: Record<string, string>, invocation: CliInvocation): 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.
+ */
+export declare function loadLeafInputs(ctx: CliContext): CliLeafInputs;
+/** @deprecated Use {@link CliContext.inputs} or {@link loadLeafInputs} via `ctx.inputs`. */
+export declare function readLeafInputs(ctx: CliContext): CliLeafInputs;
+/** @deprecated Use sync {@link readLeafInputs} — stdin is preloaded before the handler runs. */
+export declare function readLeafInputsAsync(ctx: CliContext): Promise<CliLeafInputs>;
 /** Resolved paths for `mcp bundle`. */
 export interface McpBundlePaths {
 	binaryPath: string;

package/package.json

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

package/src/cli-tool/program.ts

@@ -95,7 +95,8 @@ export const program = {
     },
     {
       key: "schemagen",
-      description: "Generate JSON Schema artifacts from src/**/schema.ts into colocated __generated__/ directories.",
+      description:
+        "Generate JSON Schema artifacts from src/**/types.ts role exports into colocated __generated__/ directories.",
       options: [
         {
           name: "root",

package/src/cli-tool/schemagen/cleanup.ts

@@ -5,7 +5,7 @@ Remove stale __generated__/ directories and files after schemagen runs.
 import { existsSync, readdirSync, rmSync, statSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import type { SchemaRoot } from "./discover-schema-roots.ts";
-import { GENERATED_DIR, SCHEMA_FILE, schemaJsonBasename } from "./names.ts";
+import { GENERATED_DIR, schemaJsonBasename, TYPES_FILE } from "./names.ts";
 
 function listGeneratedDirs(srcDir: string, projectRoot: string, out: string[]): void {
   for (const ent of readdirSync(srcDir)) {
@@ -38,8 +38,8 @@ export function cleanStaleGenerated(
 
   for (const relGeneratedDir of generatedDirs) {
     const generatedDir = join(projectRoot, relGeneratedDir);
-    const relSchemaPath = relative(projectRoot, join(dirname(generatedDir), SCHEMA_FILE));
-    const roots = existsSync(join(projectRoot, relSchemaPath)) ? (activeBySchemaFile.get(relSchemaPath) ?? []) : [];
+    const relTypesPath = relative(projectRoot, join(dirname(generatedDir), TYPES_FILE));
+    const roots = existsSync(join(projectRoot, relTypesPath)) ? (activeBySchemaFile.get(relTypesPath) ?? []) : [];
 
     if (roots.length === 0) {
       rmSync(generatedDir, { recursive: true, force: true });