External Command tool
The External Command tool pipes each block's text through an external command-line program and captures the program's standard output as the new text. It lets a pipeline reuse an existing CLI filter — a custom normalizer, a spell-fixer, a transliterator — without writing a native tool.
Text can be sent to the command on standard input or substituted into the
argument list via the ${source} and ${target} placeholders. A command is
required, and a target locale is required when applying to the target. Each
invocation has a timeout; the exit code is recorded on the block, and a
non-zero exit leaves the text unchanged and records the error.
This tool runs code the recipe chooses, so it is gated. It is exec-class:
a project that names it in a flow runs commands with your privileges and your
environment, and a recipe is bound by entering a directory. kapi therefore
asks once per project, before anything else happens with it, and remembers the
answer; an unattended run with nobody to ask refuses rather than assumes.
KAPI_TRUST_EXEC=1 grants it where the pipeline author — not the repository
being processed — is the one deciding. The same classification withholds this
tool from the agent surface, from the engine API, and from any recipe arriving
inside a .kpz. See
AD-038.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
applySource | boolean | false | Process source text |
applyTarget | boolean | true | Process target text |
args | string[] | Command arguments; use ${source} and ${target} as placeholders | |
command | string | The command to execute | |
sendAsStdin | boolean | true | Send text via stdin instead of command arguments |
targetLocale | string | Target locale for processing | |
timeout | integer | 30 | Timeout in seconds |
Configure it live
Examples
Pipe target text through a formatter
Run an external program on the target, sending text on stdin.
command: my-formatter
applyTarget: true
targetLocale: fr
Pass text as an argument
Substitute the text into the argument list instead of stdin.
command: transform
args: ["--text", "${source}"]
applySource: true
sendAsStdin: false
Processing notes
Operates on translatable blocks only; non-translatable blocks pass through unchanged.
Trailing newlines are trimmed from the captured output.
Limitations
A non-zero exit code leaves the text unchanged and records the exit code and error message as block properties.
The command runs once per block per scope (source and/or target), which can be slow for large documents.
← Back to the Tool Reference