Skip to content

REQ-O-039: --input-file Flag for Stdin Commands

Tier: Opt-In | Priority: P1

Source: §61 Bidirectional Pipe Payload Deadlock · §50 Stdin Consumption Deadlock

Addresses: Severity: Critical / Token Spend: High / Time: Critical / Context: Low

Description

The framework MUST automatically register --input-file <path> for any command that declares stdin_input: true. When --input-file is passed, the framework reads input from the file instead of stdin, bypassing the pipe buffer limit entirely. The file is read in streaming fashion; there is no size limit for file-based input. --input-file - is equivalent to stdin (preserving backward compatibility). The framework MUST document that payloads larger than 64KB should use --input-file rather than stdin piping.

A line-mode command (stdin_input: "lines" or "records", REQ-F-054) gets the same flag. It reads the file one line at a time with the command's per-line cap and no total cap, and --input-file - reads stdin as lines.

Acceptance Criteria

  • tool process --input-file /path/to/large.json reads from the file, not stdin
  • tool process --input-file - reads from stdin (equivalent to piping)
  • A 10MB file passed via --input-file is processed successfully
  • A 10MB payload via stdin to a buffered command is rejected with STDIN_TOO_LARGE and hint: "use --input-file"
  • A command that declares stdin_input: "lines" has --input-file registered, and a 10MB file of short lines passed through it is processed successfully
  • A file passed to a line-mode command whose third line exceeds the per-line cap exits 1 with LINE_TOO_LARGE and context.line: 3

Schema

No dedicated schema type — --input-file is a behavioral flag that routes input from a file path instead of stdin, with no new wire-format fields.

Wire Format

No wire-format fields — --input-file affects input routing only. The response envelope is identical to a successful stdin read.

$ tool process --input-file ./payload.json --format json

{
  "ok": true,
  "data": { "processed": true, "items": 1024 },
  "error": null,
  "warnings": [],
  "meta": { "exit_code": 0, "duration_ms": 412 }
}

Example

Opt-in: automatically registered for commands that declare stdin_input: true, "lines", or "records".

register command "process":
  stdin_input: true
  # --input-file is auto-registered by the framework

# For small payloads — stdin is fine:
$ echo '{"items":[1,2,3]}' | tool process

# For large payloads (>64KB) — use --input-file to avoid pipe buffer limit:
$ tool process --input-file ./large-payload.json

# --input-file - explicitly reads from stdin (backward compatibility):
$ cat payload.json | tool process --input-file -
Requirement Tier Relationship
REQ-F-054 F Provides: the STDIN_TOO_LARGE error that directs callers to use this flag
REQ-F-009 F Composes: non-TTY detection governs whether stdin is read at all
REQ-O-006 O Composes: stdin ID source and --input-file are complementary stdin patterns
REQ-O-004 O Composes: a records consumer reads --input-file <path> as a finished stream, so end of file ends the input