Execute Command

Execute a shell command with sandboxing and binary I/O

Overview

The Execute Command tool runs a shell command in an isolated execution directory and returns what the command printed. Binary data from upstream items can be written to disk before the command runs, so command-line tools can operate on real files. After execution, standard output can be captured as binary data instead of text, and files the command wrote to its output directory can be collected as binary properties on the output item. Timeout, output buffer size and concurrency are configurable, and commands matching known-dangerous patterns are refused.

Category: Development
Tool Name: execute_command
Version: 2

Appearance: Icon: lucide-TerminalSquare | Color: #303030

Node Type

Action (Binary) — handles file/binary data operations

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool does not require any credentials.

Parameters

Parameter	Type	Required	Default	Description
Execute Once	boolean	No	true	Whether to execute only once (using first input item) instead of once for each input item.
Command	string	Yes	—	The shell command to execute. Runs via the system shell — pipes, redirects, and chaining are supported. Binary path templates such as {{$binary.data.filePath}} are substituted before the command runs.
Materialize Binary Input	boolean	No	false	When enabled, upstream binary data properties are written to disk in the input directory before command execution. Reference them in the command via {{$binary.propertyName.filePath}}.
Capture Stdout as Binary	boolean	No	false	When enabled, stdout is captured as raw binary data and stored in the binary store. Useful for commands that produce binary output (e.g., image conversion, file generation).
Binary Property	string	No	data	Name of the binary property to write stdout data to. Names are case-sensitive — see the upstream node’s Binary Data panel for the exact names to use. (shown when Capture Stdout as Binary is true)
Output File Name	string	No	stdout_output	Filename for the captured binary data. Include extension for MIME type detection (e.g., “output.png”). (shown when Capture Stdout as Binary is true)
Capture Output Files	boolean	No	false	When enabled, files in the output directory matching the output file glob are collected as binary properties after command execution.
Output File Glob	string	No	*	Glob pattern to match files in the output directory. Only files matching this pattern are captured as binary. (shown when Capture Output Files is true)
Timeout (ms)	number	No	60000	Command timeout in milliseconds. Set to 0 for no timeout. Default: 60000 (60 seconds).
Max Buffer (bytes)	number	No	10485760	Maximum stdout/stderr buffer size in bytes. Default: 10MB. Increase for commands with large output.
Max Concurrency	number	No	1	Maximum number of items to process concurrently. Default is 1 (sequential) to avoid spawning too many child processes.

Output Data

This node replaces the input item’s JSON — the fields the item arrived with are not carried forward. Anything a downstream node needs from upstream has to be re-joined after this node. Binary data on the input item is forwarded, and any captures are merged into it.

Each output item’s JSON is:

Field	Type	Description
exitCode	number	Process exit code (0 = success)
stdout	string	Standard output text, or "[captured as binary]" when Capture Stdout as Binary is on
stderr	string	Standard error output
command	string	The resolved command that was executed, after binary path substitution
capturedFiles	array	Present only when Capture Output Files is on. One entry per captured file, each with fileName, propertyName, size and mimeType

Item count. With Execute Once on (the default) the node runs the command once against the first input item and emits exactly one output item, no matter how many items arrived. With Execute Once off it runs once per input item and emits one output item each.

Binary property names. Captured stdout is stored under the Binary Property name. Captured output files are stored under that same name when exactly one file matched the glob; when several match, each file is stored under its own file name with unsupported characters replaced by underscores.

Reference the result downstream by expression, e.g. {{ $json.exitCode }} or {{ $json.stdout }}.

Usage Examples

• Run “ls -la” and capture the directory listing
• Execute ImageMagick convert on a materialized binary input file
• Run ffmpeg to transcode a video and capture output files
• Execute a curl command to download a file and capture stdout as binary
• Run a script per input item using expressions
• Process a PDF with ghostscript and collect the output pages

Example Configuration

Run a single command and read its text output:

{
  "type": "execute_command",
  "parameters": {
    "command": "echo 'Hello, World!'",
    "executeOnce": true
  }
}

Run once per item against each item’s materialized file:

{
  "type": "execute_command",
  "parameters": {
    "command": "wc -l {{$binary.data.filePath}}",
    "executeOnce": false,
    "materializeBinaryInput": true,
    "timeout": 30000,
    "maxConcurrency": 4
  }
}

Convert an image and keep the result as binary rather than text:

{
  "type": "execute_command",
  "parameters": {
    "command": "convert input.jpg -resize 800x600 -",
    "executeOnce": true,
    "captureStdoutAsBinary": true,
    "binaryPropertyName": "resized",
    "outputFileName": "resized.jpg",
    "timeout": 60000,
    "maxBuffer": 20971520
  }
}

Materialize an upstream video, extract its audio, and capture the stream as binary:

{
  "type": "execute_command",
  "parameters": {
    "command": "ffmpeg -i {{$binary.videoFile.filePath}} -vn -acodec mp3 -",
    "executeOnce": false,
    "materializeBinaryInput": true,
    "captureStdoutAsBinary": true,
    "binaryPropertyName": "audioOutput",
    "outputFileName": "audio.mp3",
    "timeout": 120000,
    "maxBuffer": 52428800
  }
}

Collect the files a script wrote to the output directory:

{
  "type": "execute_command",
  "parameters": {
    "command": "python3 render.py --output-dir /output",
    "executeOnce": true,
    "captureOutputFiles": true,
    "outputFileGlob": "*.png",
    "timeout": 300000
  }
}

Materialize input, run a script, and collect every CSV it produced:

{
  "type": "execute_command",
  "parameters": {
    "command": "bash process.sh {{$binary.inputData.filePath}}",
    "executeOnce": false,
    "materializeBinaryInput": true,
    "captureOutputFiles": true,
    "outputFileGlob": "**/*.csv",
    "timeout": 90000,
    "maxBuffer": 10485760,
    "maxConcurrency": 2
  }
}

A one-off system command with a short timeout:

{
  "type": "execute_command",
  "parameters": {
    "command": "date +%s",
    "executeOnce": true,
    "timeout": 5000
  }
}

Extract text from each item’s PDF with an external tool:

{
  "type": "execute_command",
  "parameters": {
    "command": "pdftotext {{$binary.document.filePath}} -",
    "executeOnce": false,
    "materializeBinaryInput": true,
    "timeout": 30000,
    "maxConcurrency": 3
  }
}

Generate a QR code and store the raw PNG as a binary property:

{
  "type": "execute_command",
  "parameters": {
    "command": "qrencode -t PNG -o - 'https://example.com'",
    "executeOnce": true,
    "captureStdoutAsBinary": true,
    "binaryPropertyName": "qrCode",
    "outputFileName": "qr.png",
    "timeout": 15000
  }
}

Split a document into pages and capture them all:

{
  "type": "execute_command",
  "parameters": {
    "command": "node split-pdf.js {{$binary.document.filePath}}",
    "executeOnce": false,
    "materializeBinaryInput": true,
    "captureOutputFiles": true,
    "outputFileGlob": "page-*.pdf",
    "timeout": 180000,
    "maxBuffer": 10485760
  }
}

Process many items in parallel with a large output buffer:

{
  "type": "execute_command",
  "parameters": {
    "command": "jq -c '.results[]' {{$binary.data.filePath}}",
    "executeOnce": false,
    "materializeBinaryInput": true,
    "timeout": 60000,
    "maxBuffer": 104857600,
    "maxConcurrency": 8
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

Runs shell commands with support for binary file materialization, nsjail sandboxing, and automatic output file capture. Use when you need system-level operations like image processing, file conversion, or CLI tools not available as workflow nodes. Produces items containing stdout, stderr, exit code, and any captured binary output files.

Behavior notes

• Only {{$binary.…}} templates are substituted into the Command. Before the command runs, the node replaces {{$binary.<property>.filePath}}, {{$binary.<property>.fileName}} and {{$binary.<property>.mimeType}} with real values, and only when Materialize Binary Input is on. To build a command from item JSON, compose the string in an upstream node and pass the file through as binary instead.
• A non-zero exit code fails the item. The node treats a failed command as an error rather than passing a failed result downstream, so exitCode on a successful item is always 0. Use continue or errorPort error handling to keep the rest of the batch moving.
• Execute Once is on by default. Leave it on for setup-style commands that should run exactly once; turn it off to run the command per item, and raise Max Concurrency if you want those runs to overlap.
• Max Concurrency defaults to 1 so a large batch does not spawn a process per item all at once. Raise it deliberately.
• Output exceeding Max Buffer fails the command. Raise Max Buffer for commands that print a lot, or redirect the output to a file and capture it with Capture Output Files instead.
• Timeout 0 means no timeout. Anything else is a millisecond budget, capped at 600000 (10 minutes).
• The two capture modes are independent. Capture Stdout as Binary and Capture Output Files can be used together, separately, or not at all.
• Capture Output Files reads the command’s output directory. Have the command write its results there, then use the glob to select which of them become binary properties.
• Dangerous commands are refused. Commands matching known-destructive patterns fail before anything runs.