{
"schema_version": "1.0",
"command": "ln",
"variant": "bsd",
"match": {
"platform": ["macos", "freebsd"],
"probe": { "args": ["--version"], "expect": "failure" },
"binary_globs": ["/bin/ln", "/usr/bin/ln"]
},
"mode": "authoritative",
"confidence": "verified",
"provenance": {
"platform": "macos",
"tool_version": "macOS 26.3",
"source": "man-page",
"checked_on": "2026-07-27",
"command": "man -P cat ln | col -b",
"environment": "macOS 26.3 (Darwin arm64), system /bin/ln",
"notes": "Flags transcribed from the block after 'The options are as follows:'. COMPATIBILITY and STANDARDS were read for flags documented outside the option block; COMPATIBILITY only remarks that -h, -i, -n, -v, -w are non-standard and that -F is a FreeBSD extension, and adds no option. The option set is closed: the binary's getopt(3) option string is 'FLPfhinsvw', and -r, -t, -T, -b, -d and --symbolic are all rejected with 'illegal option', so mode is authoritative. BSD ln has no long options. conflicts_with is derived from this page only: -L/-P from 'This option cancels the -P option' and 'This option cancels the -L option'; -f/-i and -f/-w from 'The -f option overrides any previous -i and -w options' and 'The -i option overrides any previous -f options'; -s against -L and -P from the SYNOPSIS alternation 'ln [-L | -P | -s [-F]]' together with -L and -P being scoped to 'When creating a hard link to a symbolic link'. None of these combinations is diagnosed by the binary (all were run and exited 0); BSD ln resolves them last-one-wins. BSD ln rejects --version (exit 1, 'illegal option -- -'), which is why the probe matches on failure. The simplified 'link source_file target_file' form accepts no options and is not modelled here. annotations: destructive is true because -f unlinks an existing target before linking, discarding that file's directory entry irrecoverably -- the same overwrite behaviour for which cp and mv are marked destructive. Verified: 'ln -f src target' leaves target holding src's contents with the prior contents unrecoverable."
},
"description": "The ln utility creates a new directory entry (linked file) for the file name specified by target_file. The target_file will be created with the same file modes as the source_file. By default, ln makes hard links; a hard link to a file is indistinguishable from the original directory entry. Directories may not be hardlinked, and hard links may not span file systems. A symbolic link contains the name of the file to which it is linked, may span file systems and may refer to directories.",
"flags": [
{ "short": "-F", "type": "boolean", "description": "If the target file already exists and is a directory, then remove it so that the link may occur. The -F option should be used with either -f or -i options. If neither -f nor -i is specified, -f is implied. The -F option is a no-op unless -s is specified." },
{ "short": "-L", "type": "boolean", "conflicts_with": ["-P", "-s"], "description": "When creating a hard link to a symbolic link, create a hard link to the target of the symbolic link. This is the default. This option cancels the -P option." },
{ "short": "-P", "type": "boolean", "conflicts_with": ["-L", "-s"], "description": "When creating a hard link to a symbolic link, create a hard link to the symbolic link itself. This option cancels the -L option." },
{ "short": "-f", "type": "boolean", "conflicts_with": ["-i", "-w"], "description": "If the target file already exists, then unlink it so that the link may occur. The -f option overrides any previous -i and -w options." },
{ "short": "-h", "type": "boolean", "description": "If the target_file or target_dir is a symbolic link, do not follow it. This is most useful with the -f option, to replace a symlink which may point to a directory." },
{ "short": "-i", "type": "boolean", "conflicts_with": ["-f"], "description": "Cause ln to write a prompt to standard error if the target file exists. If the response from the standard input begins with the character 'y' or 'Y', then unlink the target file so that the link may occur. Otherwise, do not attempt the link. The -i option overrides any previous -f options." },
{ "short": "-n", "type": "boolean", "description": "Same as -h, for compatibility with other ln implementations." },
{ "short": "-s", "type": "boolean", "conflicts_with": ["-L", "-P"], "description": "Create a symbolic link." },
{ "short": "-v", "type": "boolean", "description": "Cause ln to be verbose, showing files as they are processed." },
{ "short": "-w", "type": "boolean", "conflicts_with": ["-f"], "description": "Warn if the source of a symbolic link does not currently exist." }
],
"positional_args": [
{ "name": "source_file", "type": "path", "variadic": true, "required": true, "description": "Existing file to link to. More than one source requires the last operand to be an existing target_dir." },
{ "name": "target_file", "type": "path", "required": false, "description": "Name of the new link, or a directory to place the link in. When omitted the link is placed in the current directory under the last component of source_file." }
],
"annotations": {
"readonly": false,
"destructive": true,
"idempotent": false,
"requires_approval": true
}
}