{
"schema_version": "1.0",
"command": "xargs",
"variant": "bsd",
"match": {
"platform": ["macos", "freebsd"],
"probe": { "args": ["--version"], "expect": "failure" },
"binary_globs": ["/usr/bin/xargs", "/bin/xargs"]
},
"mode": "authoritative",
"confidence": "verified",
"provenance": {
"platform": "macos",
"tool_version": "macOS 26.3",
"source": "man-page",
"checked_on": "2026-07-27",
"command": "man -P cat xargs | col -b",
"environment": "macOS 26.3 (Darwin arm64), system /usr/bin/xargs",
"notes": "Flags transcribed from the block after 'The options are as follows:'. STANDARDS was read for options documented outside that block and only records that -J, -o, -P, -R and -S are non-standard FreeBSD extensions, all of which are already in the option block. LEGACY DESCRIPTION was read too and is load bearing here: it says that in legacy mode '-L and -n are not mutually-exclusive', which is the only statement anywhere on this page that they ARE mutually exclusive outside legacy mode. The option set is closed by the binary: the getopt(3) option string is '+0E:I:J:L:n:oP:pR:S:s:rtx' and the long option table carries exactly eight names -- exit, interactive, max-args, max-chars, max-procs, no-run-if-empty, null and verbose -- each of which was run and accepted. mode is therefore authoritative. There are no other long options: --help, --version, --replace, --eof, --arg-file, --delimiter, --max-lines, --open-tty, --show-limits and --process-slot-var are every one rejected with \"unrecognized option\", and the last seven of those are real GNU xargs options, so this is where the two variants part company. conflicts_with was read off the running binary, since this page diagnoses nothing. Declared: -I with -J, because each clears the other -- 'xargs -J% -I@ echo % @' substitutes for @ and leaves % literal while 'xargs -I@ -J% echo % @' does the opposite, so only the later option is ever in effect; and -L with -n, on the LEGACY DESCRIPTION sentence above plus the same measured behaviour, since 'xargs -L2 -n1' groups one argument per call and 'xargs -n1 -L2' groups two lines per call. That is the same shape as BSD wc's '-c ... will cancel out any prior usage of the -m option', already recorded as a conflict in wc@bsd.json. -I with -L and with -n are accepted, with -I simply winning because it implies one line per invocation -- override groups, now recorded as conflicts. Candidates tested and REJECTED: -J with -L and with -n, which the SYNOPSIS separates but the binary accepts; and -0 with -E, which GNU xargs warns about ('the -E option has no effect if -0 or -d is used') and this one does not -- 'printf \"a\\0X\\0b\\0\" | xargs -0 -E X echo' stops at the marker, so the EOF string is still honoured and no conflict is declared. Three DEPENDENCIES were measured that conflicts_with cannot express, because it can only say 'not together', never 'requires': -x fails with the usage line unless -n is also given; and -R and -S each fail with the usage line unless -I is also given. They are recorded in the descriptions instead. Note that 'xargs -I% -x' therefore fails, but not because -I and -x clash -- 'xargs -I% -n1 -x' is accepted -- so that pairing is not a conflict either. 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 utility operand and not of any flag here, and the schema has no field for it. BSD xargs rejects --version (exit 1, \"unrecognized option `--version'\"), which is why the probe matches on failure. 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 utility operand, which this overlay cannot see. readonly is false and requires_approval is true for exactly that reason: the effect of the command 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."
},
"description": "The xargs utility reads space, tab, newline and end-of-file delimited strings from the standard input and executes utility with the strings as arguments. Any arguments specified on the command line are given to utility upon each invocation, followed by some number of the arguments read from the standard input of xargs. This is repeated until standard input is exhausted. Spaces, tabs and newlines may be embedded in arguments using single or double quotes or backslashes. If utility is omitted, echo(1) is used. Undefined behavior may occur if utility reads from the standard input. xargs exits 0 if no error occurs, 127 if utility cannot be found, 126 if utility cannot be executed, and 1 on any other error.",
"flags": [
{ "short": "-0", "long": "--null", "type": "boolean", "description": "Change xargs to expect NUL (\"\\0\") characters as separators, instead of spaces and newlines. This is expected to be used in concert with the -print0 primary in find(1). Unlike GNU xargs it does not disable the -E end-of-file marker." },
{ "short": "-E", "type": "string", "value_name": "eofstr", "description": "Use eofstr as a logical EOF marker: if it occurs as an input string, the rest of the input is ignored." },
{ "short": "-I", "type": "string", "value_name": "replstr", "conflicts_with": ["-J", "-n", "-L"], "description": "Execute utility for each input line, replacing one or more occurrences of replstr in up to replacements (or 5 if no -R flag is specified) arguments to utility with the entire line of input. The resulting arguments will not be allowed to grow beyond replsize (or 255 if no -S flag is specified) bytes. The size limit does not apply to arguments which do not contain replstr, and no replacement is done on utility itself. Implies -x." },
{ "short": "-J", "type": "string", "value_name": "replstr", "conflicts_with": ["-I"], "description": "Use the data read from standard input to replace the first occurrence of replstr instead of appending that data after all other arguments. This does not affect how many arguments are read from input (-n) or the size of the commands generated (-s); it just moves where those arguments are placed. The replstr must show up as a distinct argument to xargs and only its first occurrence is replaced." },
{ "short": "-L", "type": "integer", "value_name": "number", "conflicts_with": ["-n", "-I"], "description": "Call utility for every number lines read. If EOF is reached and fewer lines have been read than number then utility will be called with the available lines. Outside legacy mode this and -n are mutually exclusive: whichever is given last cancels the other." },
{ "short": "-n", "long": "--max-args", "type": "integer", "value_name": "number", "conflicts_with": ["-L", "-I"], "description": "Set the maximum number of arguments taken from standard input for each invocation of utility. An invocation will use fewer than number arguments if the accumulated byte count exceeds the -s size or there are fewer arguments remaining. The current default value for number is 5000. Outside legacy mode this and -L are mutually exclusive: whichever is given last cancels the other." },
{ "short": "-o", "type": "boolean", "description": "Reopen stdin as /dev/tty in the child process before executing the command. This is useful if you want xargs to run an interactive application." },
{ "short": "-P", "long": "--max-procs", "type": "integer", "value_name": "maxprocs", "description": "Parallel mode: run at most maxprocs invocations of utility at once. If maxprocs is set to 0, xargs will run as many processes as possible." },
{ "short": "-p", "long": "--interactive", "type": "boolean", "description": "Echo each command to be executed and ask the user whether it should be executed. An affirmative response, 'y' in the POSIX locale, causes the command to be executed; any other response causes it to be skipped. No commands are executed if the process is not attached to a terminal." },
{ "short": "-r", "long": "--no-run-if-empty", "type": "boolean", "description": "Accepted for compatibility with GNU xargs, where it inhibits running the utility on empty input. This implementation never runs the utility on empty input in the first place, so the option does nothing." },
{ "short": "-R", "type": "integer", "value_name": "replacements", "description": "Specify the maximum number of arguments that -I will do replacement in. If replacements is negative, the number of arguments in which to replace is unbounded. It REQUIRES -I: given on its own the binary prints the usage line and exits 1." },
{ "short": "-S", "type": "integer", "value_name": "replsize", "description": "Specify the amount of space (in bytes) that -I can use for replacements. The default for replsize is 255. It REQUIRES -I: given on its own the binary prints the usage line and exits 1." },
{ "short": "-s", "long": "--max-chars", "type": "integer", "value_name": "size", "description": "Set the maximum number of bytes for the command line length provided to utility. The sum of the length of the utility name, the arguments passed to utility (including NULL terminators) and the current environment will be less than or equal to this number. The current default value for size is ARG_MAX - 4096." },
{ "short": "-t", "long": "--verbose", "type": "boolean", "description": "Echo the command to be executed to standard error immediately before it is executed." },
{ "short": "-x", "long": "--exit", "type": "boolean", "description": "Force xargs to terminate immediately if a command line containing number arguments will not fit in the specified (or default) command line length. It REQUIRES -n: given on its own, or with only -I or -L, the binary prints the usage line and exits 1." }
],
"positional_args": [
{ "name": "utility", "type": "string", "required": false, "description": "The program to execute for each batch of arguments. If omitted, echo(1) is used. This operand is where the risk of an xargs invocation lives: xargs itself neither writes nor deletes anything, and whatever the utility does is beyond what this overlay can describe." },
{ "name": "argument", "type": "string", "variadic": true, "required": false, "description": "Initial arguments given to utility on every invocation, before the arguments read from standard input." }
],
"annotations": {
"readonly": false,
"destructive": false,
"idempotent": false,
"requires_approval": true
}
}