Execute Command Plus

Execute shell command with forgiving error handling for AI agents

Execute Command Plus

AI-generated

Summary

Runs a shell command on the n8n host, once per input item or once in total, and returns the result in a compact AI-oriented string, stdout only, or a detailed JSON object. By default it is forgiving: command failures don't stop the workflow.

Inputs

  • command (required) — Shell command to run. It is read once from item 0, so it is the same for every item. Input item data is not passed to the command unless an n8n expression resolves in item 0.
  • executeOnce — If on, only the first input item is processed and one command runs. If off (default), the command runs once per input item.
  • forgiving — Default on. Command errors, including non-zero exit, timeout and buffer overflow, are reported in the output and the workflow continues. If off, the error is thrown and the node fails.
  • delay — Milliseconds to sleep before each execution. Default 0.
  • encoding (required) — Character encoding used to decode stdout and stderr via iconv-lite. Default utf-8.
  • cwd — Working directory for the command. Empty uses the process default.
  • timeout — Maximum run time in ms. Default 120000. The process is killed with the kill signal when it is exceeded.
  • shell — Shell used to run the command: /bin/bash (default), /bin/sh, /usr/bin/bash or /usr/bin/zsh.
  • maxBuffer — Maximum stdout/stderr buffer in KB. Default 1024.
  • killSignal — Signal sent on timeout: SIGTERM (default), SIGKILL or SIGINT.
  • outputMode — ai (default): a single output string. stdout: output holds trimmed stdout. json: structured fields success, exitCode, stdout, stderr and error.

Output shape

A list of items, one per executed command, each paired to its input item index. Item fields depend on Output Mode. ai: output = "OK | " or "ERR | ", then " | " and " | " when present, with " | verify result" appended when there is stdout or an error. stdout: output = trimmed stdout, or "(no output)". json: success, exitCode, stdout, stderr, error.

If the command is blank and all input items are empty, it returns one item saying "No fields - item(s) exist, but they're empty" (json mode returns success:false and an error field). With Forgiving off, the first failing command throws and stops the node. The command runs with the n8n process environment, and stdout and stderr are trimmed. In ai and stdout modes stderr is not returned. In ai mode the exit code is the process exit code. If the child is killed by a signal, the exit code is 0 even when an error is reported, and "ERR" then shows 1.

Examples

Example 1: Let an AI agent run a shell command as a tool and see compact results

command: ls -la /data, Output Mode: ai, Forgiving Mode: on

Example 2: Run a script once and branch on its exit code

command: ./backup.sh, Execute Once: on, Output Mode: json, Forgiving Mode: on, then use an IF node on {{$json.exitCode}}

Example 3: Fail the workflow if a long-running command errors

command: python job.py, Forgiving Mode: off, Timeout: 600000, Kill Signal: SIGKILL, Working Directory: /opt/jobs

Links

Discussion