Skip to main content

Shell

Executes shell commands with timeout control, environment management, and background execution support.

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Waits in seconds after executing node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.

Inputs​

  • Command - string - The shell command to execute (required).
  • Description - string - Clear, concise description of what this command does in 5-10 words (optional).
  • Timeout - int - Timeout in milliseconds, max 600000 (10 minutes), default 120000 (2 minutes) (optional).
  • Run in Background - bool - Set to true to run this command in the background (optional, default: false).

Options​

  • Working Directory - string - Working directory for command execution (default: current directory).
  • Environment Variables - object - Additional environment variables as key-value pairs (optional).
  • Shell - Shell to use: Auto Detect, Bash, Sh, Cmd (Windows), PowerShell (default: Auto Detect).

Outputs​

  • Stdout - string - Standard output from the command.
  • Stderr - string - Standard error from the command.
  • Exit Code - int - Exit code of the command (0 = success).
  • Combined Output - string - Combined stdout and stderr.
  • Execution Info - object - Detailed execution information:
    • command - The executed command
    • description - Command description
    • shell - Shell used
    • workingDir - Working directory
    • exitCode - Exit code
    • duration - Execution time in milliseconds
    • timedOut - Whether the command timed out
    • startTime - Start time (ISO 8601)
    • platform - Operating system
    • arch - System architecture
    • background - Whether run in background
    • shellID - Background shell ID (if applicable)
  • Shell ID - string - ID of the background shell (only for background execution).

How It Works​

The Shell node executes commands in a shell environment. When executed, the node:

Foreground Execution (Run in Background = false)​

  1. Validates the command is not empty
  2. Determines the shell to use (auto-detect or specified)
  3. Sets up working directory and environment variables
  4. Creates command with timeout context
  5. Executes the command
  6. Captures stdout and stderr separately
  7. Waits for command completion or timeout
  8. Returns output and exit code

Background Execution (Run in Background = true)​

  1. Validates the command
  2. Generates unique shell ID
  3. Creates command without timeout
  4. Sets up pipes for stdout and stderr
  5. Starts command asynchronously
  6. Registers background shell in registry
  7. Returns immediately with shell ID
  8. Streams output to background shell registry
  9. Updates status when command completes

Requirements​

  • Non-empty command string
  • Appropriate shell available on the system
  • Execute permissions for the command
  • Read/write access to working directory

Error Handling​

The node will return specific errors in the following cases:

  • Missing command - "Command is required"
  • Empty command - "Command cannot be empty"
  • Timeout exceeded - "Command timed out after {{N}} ms"
  • Execution failed - "Command execution failed: {{error}}"
  • Background start failed - "Failed to start background command: {{error}}"

Usage Examples​

Simple Command​

Command: ls -la
Description: List all files in directory

Command with Timeout​

Command: npm install
Description: Install npm dependencies
Timeout: 300000

Background Process​

Command: python long_running_script.py
Description: Run data processing script
Run in Background: true

Command with Environment Variables​

Command: node app.js
Working Directory: /home/user/app
Environment Variables: {
  "NODE_ENV": "production",
  "PORT": "3000"
}

Multiple Commands​

Command: cd /app && npm test && npm run build
Description: Run tests and build
Timeout: 600000

Windows PowerShell Command​

Command: Get-Process | Where-Object \{$_.CPU -gt 100\}
Shell: PowerShell
Description: Find high CPU processes

Shell Detection​

The node auto-detects the appropriate shell based on the operating system:

Linux/macOS​

  • Tries bash first
  • Falls back to sh if bash not available

Windows​

  • Tries PowerShell first
  • Falls back to cmd if PowerShell not available

You can override auto-detection with the Shell option.

Usage Notes​

  • Commands run in the specified or current working directory
  • Output is truncated at 30,000 characters to prevent memory issues
  • Background processes are not subject to timeout
  • Environment variables are merged with system environment
  • Exit code 0 typically indicates success
  • Non-zero exit codes may indicate errors (but not always)
  • Use Bash Output node to retrieve background process output
  • Use Kill Bash node to terminate background processes
  • The command is passed to the shell, so shell features work (pipes, redirects, etc.)

Background Execution​

When Run in Background is true:

  • Command starts immediately and returns shell ID
  • No timeout is enforced
  • Output is streamed to the registry
  • Use Bash Output node with shell ID to retrieve output
  • Use Kill Bash node with shell ID to terminate
  • Multiple background shells can run simultaneously

Common Use Cases​

Build and Deployment​

Run build scripts, tests, and deployment commands.

System Administration​

Execute system commands, manage services, check status.

Data Processing​

Run scripts for data transformation and analysis.

File Operations​

Use shell commands for bulk file operations.

Package Management​

Install dependencies, update packages.

Long-Running Tasks​

Start background processes for long-running tasks.

Best Practices​

  • Set appropriate timeouts based on expected execution time
  • Use background execution for long-running processes
  • Provide descriptions for better logging and debugging
  • Check exit codes to determine success/failure
  • Handle stderr to catch error messages
  • Use absolute paths in commands for consistency
  • Set working directory when needed
  • Validate commands before execution
  • Monitor background processes with Bash Output
  • Clean up background processes with Kill Bash

Security Notes​

  • Commands are executed in a shell, so shell injection is possible
  • Never pass unsanitized user input directly to commands
  • Validate and sanitize all command inputs
  • Use environment variables for sensitive data instead of embedding in commands
  • Be cautious with sudo or elevated permissions
  • Review commands before execution in production

Comparison with Other Nodes​

  • Shell vs Bash Output: Shell executes commands; Bash Output retrieves output from background shells
  • Shell vs Kill Bash: Shell starts processes; Kill Bash terminates them
  • Shell vs Read/Write: Shell executes commands; Read/Write operate on files directly