{
"schema_version": "1.0",
"command": "xargs",
"variant": "gnu",
"match": {
"probe": {
"args": ["--version"],
"expect": "success",
"output_contains": "GNU findutils"
}
},
"mode": "authoritative",
"confidence": "verified",
"provenance": {
"platform": "linux",
"tool_version": "4.10.0",
"package": "findutils",
"source": "help",
"checked_on": "2026-07-27",
"command": "docker run --rm debian@sha256:328d16499860ae6cb9b345e2e4cebca08c2a36e4f7278482c7bd1f39d71e5bfd xargs --help",
"environment": "debian@sha256:328d16499860ae6cb9b345e2e4cebca08c2a36e4f7278482c7bd1f39d71e5bfd",
"notes": "Debian slim images ship no man pages, so the flag list was read from GNU --help, which is complete by GNU convention, and every entry was then run against the binary to establish its argument shape, which --help states only loosely. Three options take an OPTIONAL attached value and silently mis-parse a separated one: 'xargs -eX' sets the EOF string while 'xargs -e X echo' runs X as the command; 'xargs -l2' groups two lines while 'xargs -l 2' runs 2 as the command; 'xargs -i@' sets the replacement string while 'xargs -i @' runs @ as the command. -I and -L by contrast REQUIRE their value. mode is authoritative on that basis. Five options that BSD xargs has were tested and are absent here: -J, -R and -S are rejected outright, and BSD's --exit/--verbose/--interactive spellings do exist here while its bare -J replacement model does not. conflicts_with was read off the running binary, which names each clash explicitly, and the whole option set was tested pair by pair. Declared: --max-args (-n), --max-lines (-L, -l) and --replace (-I, -i) are pairwise mutually exclusive -- 'options --max-lines and --max-args/-n are mutually exclusive', 'options --replace and -L are mutually exclusive' and 'options --max-args and --replace/-I/-i are mutually exclusive' -- and the EOF options (-E, -e) clash with the delimiter options (-0, -d), diagnosed as 'the -E option has no effect if -0 or -d is used' and also stated in --help as '(ignored if -0 or -d was specified)'. The -n/-I warning is asymmetric, appearing only when -n is given first, because the binary warns when it overrides an already-set value; the exclusivity itself is not, so both directions are declared. -0 with -d is accepted with the later one winning -- an override group, now recorded as a conflict. Candidates tested and REJECTED: -p with -t; -a with a live standard input, where the file simply wins and nothing is diagnosed; and -x with everything, since unlike BSD xargs it needs no companion option here. Note that BSD xargs accepts -0 together with -E and still honours the marker, so that conflict is declared on the GNU side only -- each variant's conflicts came from its own evidence. No flag is marked long_running. xargs itself always terminates once its input is exhausted; a command it launches may not, but that is a property of the COMMAND operand rather than of any flag here, and the schema has no field for it. annotations: xargs has no hazard of its own -- it opens nothing for writing and deletes nothing -- so destructive is false, which is the honest reading: the damage a given invocation can do belongs to the COMMAND operand, which this overlay cannot see. readonly is false and requires_approval is true for exactly that reason: the effect is unbounded and cannot be judged from xargs's own flags, so an approval gate is the only correct default. idempotent is false on the same argument. No schema field was invented to carry this; it is stated in the operand description and here. conflicts_with was extended in a later pass, after the field's definition widened to cover override groups as well as diagnosed errors: apexe's input is a JSON object, which carries no ordering, so for a last-one-wins group which flag actually wins is decided by the order the caller happened to write the keys in. Every pair added then was run in BOTH orders against the reference build recorded above, and only pairs whose outcome depends on that order, or where one side is silently discarded, were added. value_optional was added on 2026-08-24, read off the reference build recorded above. GNU --help spells an optional option argument as `--opt[=VAL]` and a required one as `--opt=VAL`; every flag marked here shows the bracketed form and was then run in BOTH spellings, because the notation alone is not evidence. `xargs --replace X echo '[X]'` is \"xargs: X: No such file or directory\" (exit 127) -- the value was taken as the utility to run -- while `xargs --replace=X echo '[X]'` runs echo once per input line; --eof behaves the same. A probe with empty stdin is useless here and was discarded: both spellings exit 0 because xargs runs nothing."
},
"description": "Run COMMAND with arguments INITIAL-ARGS and more arguments read from input. If COMMAND is omitted, echo is used. Input items are separated by whitespace by default, with quote and backslash processing and logical end-of-file processing enabled; -0 and -d turn all three off.",
"flags": [
{ "short": "-0", "long": "--null", "type": "boolean", "conflicts_with": ["-E", "-e", "-d"], "description": "Items are separated by a null, not whitespace; disables quote and backslash processing and logical EOF processing. Giving -E or -e as well is diagnosed with 'the -E option has no effect if -0 or -d is used'." },
{ "short": "-a", "long": "--arg-file", "type": "path", "value_name": "FILE", "description": "Read arguments from FILE, not standard input. If standard input also has data it is simply not read, and nothing is diagnosed." },
{ "short": "-d", "long": "--delimiter", "type": "string", "value_name": "CHARACTER", "conflicts_with": ["-E", "-e", "-0"], "description": "Items in input stream are separated by CHARACTER, not by whitespace; disables quote and backslash processing and logical EOF processing. Giving -E or -e as well is diagnosed with 'the -E option has no effect if -0 or -d is used'." },
{ "short": "-E", "type": "string", "value_name": "END", "conflicts_with": ["-0", "-d"], "description": "Set logical EOF string; if END occurs as a line of input, the rest of the input is ignored. It is ignored if -0 or -d was specified, which the binary warns about. The value is required and may be separated." },
{ "short": "-e", "long": "--eof", "type": "string", "value_name": "END", "value_optional": true, "conflicts_with": ["-0", "-d"], "description": "Equivalent to -E END if END is specified; otherwise there is no end-of-file string. The value is OPTIONAL and must be attached, as in -eEND or --eof=END; 'xargs -e END command' runs END as the command instead." },
{ "short": "-I", "type": "string", "value_name": "R", "conflicts_with": ["-L", "-l", "-n"], "description": "Same as --replace=R: replace R in INITIAL-ARGS with names read from standard input, split at newlines. The value is REQUIRED here, unlike -i where it is optional." },
{ "short": "-i", "long": "--replace", "type": "string", "value_name": "R", "value_optional": true, "conflicts_with": ["-L", "-l", "-n"], "description": "Replace R in INITIAL-ARGS with names read from standard input, split at newlines; if R is unspecified, assume {}. The value is OPTIONAL and must be attached, as in -i@ or --replace=@; 'xargs -i @ command' runs @ as the command instead." },
{ "short": "-L", "long": "--max-lines", "type": "integer", "value_name": "MAX-LINES", "conflicts_with": ["-n", "-I", "-i"], "description": "Use at most MAX-LINES non-blank input lines per command line. The value is required." },
{ "short": "-l", "type": "integer", "value_name": "MAX-LINES", "conflicts_with": ["-n", "-I", "-i"], "description": "Similar to -L but defaults to at most one non-blank input line if MAX-LINES is not specified. The value is OPTIONAL and must be attached, as in -l2; 'xargs -l 2 command' runs 2 as the command instead." },
{ "short": "-n", "long": "--max-args", "type": "integer", "value_name": "MAX-ARGS", "conflicts_with": ["-L", "-l", "-I", "-i"], "description": "Use at most MAX-ARGS arguments per command line." },
{ "short": "-o", "long": "--open-tty", "type": "boolean", "description": "Reopen stdin as /dev/tty in the child process before executing the command; useful to run an interactive application. It fails where /dev/tty cannot be opened, as in a container without a controlling terminal." },
{ "short": "-P", "long": "--max-procs", "type": "integer", "value_name": "MAX-PROCS", "description": "Run at most MAX-PROCS processes at a time." },
{ "short": "-p", "long": "--interactive", "type": "boolean", "description": "Prompt before running commands. The prompt is read from /dev/tty, so it fails where that cannot be opened." },
{ "long": "--process-slot-var", "type": "string", "value_name": "VAR", "description": "Set environment variable VAR in child processes to the index of the process slot the child is running in." },
{ "short": "-r", "long": "--no-run-if-empty", "type": "boolean", "description": "If there are no arguments, then do not run COMMAND; if this option is not given, COMMAND will be run at least once. This is where GNU xargs differs from BSD xargs, which never runs the command on empty input." },
{ "short": "-s", "long": "--max-chars", "type": "integer", "value_name": "MAX-CHARS", "description": "Limit length of command line to MAX-CHARS." },
{ "long": "--show-limits", "type": "boolean", "description": "Show limits on command-line length, including the maximum parallelism --max-procs may be given, and then process the input as usual." },
{ "short": "-t", "long": "--verbose", "type": "boolean", "description": "Print commands before executing them." },
{ "short": "-x", "long": "--exit", "type": "boolean", "description": "Exit if the size (see -s) is exceeded. Unlike BSD xargs it needs no companion option and is accepted on its own." },
{ "long": "--help", "type": "boolean", "description": "Display this help and exit." },
{ "long": "--version", "type": "boolean", "description": "Output version information and exit. This build answers with 'xargs (GNU findutils) 4.10.0'." }
],
"positional_args": [
{ "name": "command", "type": "string", "required": false, "description": "The program to run for each batch of arguments. If omitted, echo is used. This operand is where the risk of an xargs invocation lives: xargs itself neither writes nor deletes anything, and whatever the command does is beyond what this overlay can describe." },
{ "name": "initial-args", "type": "string", "variadic": true, "required": false, "description": "Initial arguments given to COMMAND on every invocation, before the arguments read from input. With -i or -I these are also where the replacement string is looked for." }
],
"annotations": {
"readonly": false,
"destructive": false,
"idempotent": false,
"requires_approval": true
}
}