<!-- BusyBot node reference — https://busybot.net/tools/execute-command/ -->

> Node: Execute Command (`execute_command`) · Action (binary) · v2
> Category: Development · Credentials: none
> Updated: 2026-08-16

# 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:

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

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

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

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

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

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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.