Runner: Cmd
AI-generatedOverview
This node executes one or more command-line instructions (shell commands) provided as input. It is useful for automating system-level tasks, running scripts, or interacting with the operating system directly from an n8n workflow. Typical use cases include listing directory contents, managing files, invoking custom scripts, or any scenario where shell commands are needed to extend workflow capabilities.
For example, you could run ls to list files in a directory, execute a script to process data, or run commands that interact with other software installed on the host machine.
Properties
| Name | Meaning |
|---|---|
| Cmd | The command(s) to run, specified as a JSON array of strings representing the shell command and its arguments. For example: ["ls", "-la"]. This property is required. |
| Advanced Config | A collection of optional advanced settings including: |
| - Envs: Environment variables to set when running the command, each with a key and value. | |
| - Files: Files to create or modify before running the command, each with a name and content. | |
| - Collect Files: Names of files to collect after command execution. | |
| Debug Mode | Boolean flag to enable debug mode, which provides more detailed information in the node's input and output for troubleshooting purposes. Defaults to false. |
Output
The node outputs a JSON object containing the results of the executed command(s). The main output field is:
response: An array containing the result(s) of the command execution wrapped by a proxy runner. This typically includes standard output, standard error, exit codes, and possibly collected files if configured.
If binary data is involved (e.g., collected files), it will be included according to the advanced configuration but is not explicitly detailed in the static code.
Dependencies
- The node relies on the ability to execute shell commands on the host environment where n8n is running.
- No external API keys or services are required.
- Proper permissions must be granted to the n8n process to execute shell commands and access the filesystem if using file-related advanced options.
Troubleshooting
Common issues:
- Commands failing due to insufficient permissions.
- Incorrect command syntax leading to errors.
- Environment variables not being set correctly.
- File creation or collection failing due to path or permission issues.
Error messages:
- Errors related to command execution usually reflect the underlying shell error messages.
- If the node fails silently, enabling Debug Mode can provide more insight into what was executed and any errors encountered.
Resolutions:
- Verify command syntax and test commands independently in a terminal.
- Ensure n8n has necessary permissions to execute commands and access files.
- Use Debug Mode to get detailed logs.
- Check environment variable names and values for correctness.
Links and References
- Node.js child_process documentation – for understanding how commands might be executed under the hood.
- n8n Documentation – general guidance on creating and using custom nodes.
- Shell command references depending on your OS (e.g., Bash, PowerShell).