CLI Integration¶

Overview¶

CLI nodes in NebulaFlow execute shell commands and scripts via Node.js child_process. This guide covers configuration, usage, and best practices for CLI integration.

CLI Node Configuration¶

Basic Configuration¶

interface CLINode {
    type: NodeType.CLI
    data: {
        title: string
        content: string  // Command to execute
        active: boolean
        mode?: 'command' | 'script'
        shell?: 'bash' | 'sh' | 'zsh' | 'pwsh' | 'cmd'
        safetyLevel?: 'safe' | 'advanced'
        streamOutput?: boolean
        stdin?: {
            source?: 'none' | 'parents-all' | 'parent-index' | 'literal'
            parentIndex?: number
            literal?: string
            stripCodeFences?: boolean
            normalizeCRLF?: boolean
        }
        env?: {
            exposeParents?: boolean
            names?: string[]
            static?: Record<string, string>
        }
        flags?: {
            exitOnError?: boolean
            unsetVars?: boolean
            pipefail?: boolean
            noProfile?: boolean
            nonInteractive?: boolean
            executionPolicyBypass?: boolean
        }
    }
}

Example Configurations¶

Basic Command¶

{
    type: NodeType.CLI,
    data: {
        title: 'Git Status',
        content: 'git status',
        active: true,
        mode: 'command',
        shell: 'bash',
        streamOutput: true
    }
}

Command with Input¶

{
    type: NodeType.CLI,
    data: {
        title: 'Process File',
        content: 'cat ${1} | grep "error"',
        active: true,
        mode: 'command',
        stdin: {
            source: 'parent-index',
            parentIndex: 0
        }
    }
}

Script Execution¶

{
    type: NodeType.CLI,
    data: {
        title: 'Run Script',
        content: '#!/bin/bash\necho "Hello from script"\nls -la',
        active: true,
        mode: 'script',
        shell: 'bash'
    }
}

Command with Environment Variables¶

{
    type: NodeType.CLI,
    data: {
        title: 'Build with Env',
        content: 'npm run build',
        active: true,
        env: {
            static: {
                NODE_ENV: 'production',
                API_KEY: '${apiKey}'
            },
            exposeParents: true,
            names: ['PATH', 'HOME']
        }
    }
}

Safe Command (Requires Approval)¶

{
    type: NodeType.CLI,
    data: {
        title: 'Delete Files',
        content: 'rm -rf /tmp/temp-*',
        active: true,
        safetyLevel: 'safe',
        needsUserApproval: true
    }
}

Advanced Command (Bypasses Approval)¶

{
    type: NodeType.CLI,
    data: {
        title: 'System Cleanup',
        content: 'sudo apt-get autoremove -y',
        active: true,
        safetyLevel: 'advanced',
        flags: {
            executionPolicyBypass: true
        },
        dangerouslyAllowAll: true
    }
}

Command Modes¶

Command Mode¶

Default mode - Execute a single command:

{
    data: {
        mode: 'command',
        content: 'git status'
    }
}

Use when: - Running single commands - Simple operations - Quick tasks

Script Mode¶

Execute multi-line scripts:

{
    data: {
        mode: 'script',
        content: `#!/bin/bash
echo "Starting build..."
npm install
npm run build
echo "Build complete!"`
    }
}

Use when: - Multi-step operations - Complex logic - Reusable scripts

Shell Selection¶

Available Shells¶

Shell	Platform	Use Case
`bash`	Linux/macOS	Default, feature-rich
`sh`	Unix	Minimal, portable
`zsh`	Linux/macOS	Advanced features
`pwsh`	Windows	PowerShell Core
`cmd`	Windows	Legacy Windows

Configuration¶

{
    data: {
        shell: 'bash'  // Choose based on platform
    }
}

Platform Detection¶

Best practice: Use platform-appropriate shell:

// For cross-platform workflows
{
    data: {
        shell: process.platform === 'win32' ? 'cmd' : 'bash'
    }
}

Input Handling¶

Input Sources¶

None (Default)¶

No stdin input:

{
    data: {
        stdin: {
            source: 'none'
        }
    }
}

Parent Index¶

Input from specific parent node:

{
    data: {
        stdin: {
            source: 'parent-index',
            parentIndex: 0  // First parent
        }
    }
}

Parents All¶

Input from all parent nodes:

{
    data: {
        stdin: {
            source: 'parents-all'
        }
    }
}

Literal¶

Static input string:

{
    data: {
        stdin: {
            source: 'literal',
            literal: 'Hello, World!'
        }
    }
}

Input Processing Options¶

Strip Code Fences¶

Remove markdown code fences:

{
    data: {
        stdin: {
            source: 'parent-index',
            parentIndex: 0,
            stripCodeFences: true
        }
    }
}

Normalize CRLF¶

Convert Windows line endings:

{
    data: {
        stdin: {
            source: 'parent-index',
            parentIndex: 0,
            normalizeCRLF: true
        }
    }
}

Environment Variables¶

Static Variables¶

Define variables directly:

{
    data: {
        env: {
            static: {
                NODE_ENV: 'production',
                API_KEY: '${apiKey}',
                PATH: '/usr/local/bin:${PATH}'
            }
        }
    }
}

Parent Variables¶

Inherit variables from parent nodes:

{
    data: {
        env: {
            exposeParents: true
        }
    }
}

Named Variables¶

Select specific environment variables:

{
    data: {
        env: {
            names: ['PATH', 'HOME', 'USER']
        }
    }
}

Variable Substitution¶

Use template variables in commands:

{
    data: {
        content: 'echo "Hello ${userName}"',
        env: {
            static: {
                userName: '${user.name}'
            }
        }
    }
}

Execution Flags¶

Exit on Error¶

Stop execution on command failure:

{
    data: {
        flags: {
            exitOnError: true
        }
    }
}

Unset Variables¶

Clear inherited variables:

{
    data: {
        flags: {
            unsetVars: true
        }
    }
}

Pipefail¶

Fail if any command in pipe fails:

{
    data: {
        flags: {
            pipefail: true
        }
    }
}

No Profile¶

Skip shell profile loading:

{
    data: {
        flags: {
            noProfile: true
        }
    }
}

Non-Interactive¶

Run in non-interactive mode:

{
    data: {
        flags: {
            nonInteractive: true
        }
    }
}

Execution Policy Bypass¶

Bypass safety checks (use with caution):

{
    data: {
        flags: {
            executionPolicyBypass: true
        },
        dangerouslyAllowAll: true
    }
}

Safety Levels¶

Safe Mode (Default)¶

Features: - Requires approval for dangerous commands - Validates command syntax - Limits execution time - Restricts file system access

Use when: - Running user-provided commands - Production environments - Security-critical operations

Example:

{
    data: {
        safetyLevel: 'safe',
        needsUserApproval: true
    }
}

Advanced Mode¶

Features: - Bypasses some safety checks - Allows dangerous commands - Requires explicit bypass flag

Use when: - Trusted environments - System administration - Development workflows

Example:

{
    data: {
        safetyLevel: 'advanced',
        flags: {
            executionPolicyBypass: true
        },
        dangerouslyAllowAll: true
    }
}

Approval System¶

How It Works¶

Pending - Node status: pending_approval
Prompt - User sees approval dialog
Decision - Approve or reject
Execution - Approved nodes execute

Approval Dialog¶

The dialog shows: - Command to execute - Safety level - Potential risks - Approval/reject buttons

Bypassing Approval¶

Warning: Only use in trusted environments.

{
    data: {
        dangerouslyAllowAll: true,
        flags: {
            executionPolicyBypass: true
        }
    }
}

Output Streaming¶

Streaming Output¶

Enable real-time output streaming:

{
    data: {
        streamOutput: true
    }
}

Output Events¶

Streaming output is sent via events:

{
    type: 'node_output_chunk',
    data: {
        nodeId: 'cli-node-1',
        chunk: 'Building project...\n',
        stream: 'stdout'
    }
}

Output Streams¶

stdout: Standard output

{ stream: 'stdout' }

stderr: Error output

{ stream: 'stderr' }

Common Use Cases¶

File Operations¶

List Files¶

{
    data: {
        title: 'List Files',
        content: 'ls -la',
        streamOutput: true
    }
}

Copy Files¶

{
    data: {
        title: 'Copy Files',
        content: 'cp -r ${source} ${destination}',
        env: {
            static: {
                source: '${sourcePath}',
                destination: '${destPath}'
            }
        }
    }
}

Search Files¶

{
    data: {
        title: 'Search Files',
        content: 'find . -name "*.js" -type f',
        streamOutput: true
    }
}

Git Operations¶

Status¶

{
    data: {
        title: 'Git Status',
        content: 'git status',
        streamOutput: true
    }
}

Commit¶

{
    data: {
        title: 'Git Commit',
        content: 'git commit -m "${message}"',
        env: {
            static: {
                message: '${commitMessage}'
            }
        }
    }
}

Push¶

{
    data: {
        title: 'Git Push',
        content: 'git push origin ${branch}',
        env: {
            static: {
                branch: '${gitBranch}'
            }
        }
    }
}

Build Operations¶

npm Install¶

{
    data: {
        title: 'Install Dependencies',
        content: 'npm install',
        streamOutput: true
    }
}

Build¶

{
    data: {
        title: 'Build Project',
        content: 'npm run build',
        env: {
            static: {
                NODE_ENV: 'production'
            }
        },
        streamOutput: true
    }
}

Test¶

{
    data: {
        title: 'Run Tests',
        content: 'npm test',
        streamOutput: true
    }
}

System Operations¶

System Info¶

{
    data: {
        title: 'System Info',
        content: 'uname -a && free -h && df -h',
        streamOutput: true
    }
}

Process Management¶

{
    data: {
        title: 'List Processes',
        content: 'ps aux | grep node',
        streamOutput: true
    }
}

Disk Usage¶

{
    data: {
        title: 'Disk Usage',
        content: 'du -sh * | sort -hr',
        streamOutput: true
    }
}

API Integration¶

Fetch Data¶

{
    data: {
        title: 'Fetch API Data',
        content: 'curl https://api.example.com/data',
        streamOutput: true
    }
}

POST Data¶

{
    data: {
        title: 'Send Data',
        content: 'curl -X POST -H "Content-Type: application/json" -d \'${data}\' https://api.example.com/data',
        stdin: {
            source: 'parent-index',
            parentIndex: 0
        }
    }
}

With Authentication¶

{
    data: {
        title: 'Authenticated Request',
        content: 'curl -H "Authorization: Bearer ${apiKey}" https://api.example.com/protected',
        env: {
            static: {
                apiKey: '${apiKey}'
            }
        }
    }
}

Integration Patterns¶

Pattern 1: Sequential Commands¶

CLI Node A (command 1)
    └── CLI Node B (command 2)
    └── CLI Node C (command 3)

Example:

npm install
    └── npm run build
    └── npm test

Pattern 2: Parallel Commands¶

CLI Node A ──┐
CLI Node B ──┤ → CLI Node D
CLI Node C ──┘

Example:

Build A ──┐
Build B ──┤ → Deploy
Build C ──┘

Pattern 3: Command with Input¶

Text Node (input)
    └── CLI Node (process input)
    └── Preview Node (result)

Example:

"File path: /path/to/file.txt"
    └── cat ${1}
    └── Display content

Pattern 4: Conditional Commands¶

IF Node (condition)
    ├── True: CLI (command A)
    └── False: CLI (command B)

Example:

IF file exists
    ├── True: cat file.txt
    └── False: echo "File not found"

Pattern 5: Loop Commands¶

Loop Start (iterations=5)
    └── CLI Node (process item ${i})
Loop End

Example:

Loop Start (i=0 to 4)
    └── process item ${i}
Loop End

Performance Optimization¶

Command Efficiency¶

Use appropriate shell - bash for speed, sh for compatibility
Minimize I/O - Reduce file operations
Use built-ins - Prefer shell built-ins over external commands
Parallel execution - Use workflow parallelism

Output Handling¶

Stream output - For long-running commands
Filter output - Use grep, jq, etc.
Limit output - Use head, tail, etc.
Parse efficiently - Use appropriate tools

Resource Management¶

Set timeouts - Prevent hanging processes
Limit concurrency - Use workflow settings
Monitor resources - Track CPU/memory usage
Clean up - Remove temporary files

Security Considerations¶

Command Injection¶

Never directly interpolate user input:

// Bad: Direct interpolation
content: "echo ${userInput}"  // Risk of injection

// Good: Use stdin
stdin: {
    source: 'parent-index',
    parentIndex: 0
}
content: "cat"

Dangerous Commands¶

Avoid or require approval: - rm -rf / - sudo - format - shutdown

File System Access¶

Restrict access:

{
    data: {
        flags: {
            executionPolicyBypass: false
        },
        disabledTools: ['filesystem']
    }
}

Environment Security¶

Don't expose sensitive variables:

// Bad: Exposing all variables
env: { exposeParents: true }

// Good: Selective exposure
env: {
    names: ['PATH', 'HOME']
}

Troubleshooting¶

Common Issues¶

"Command not found"¶

Cause: Command not in PATH

Solution:

{
    data: {
        content: "/full/path/to/command",
        env: { exposeParents: true }
    }
}

"Permission denied"¶

Cause: Insufficient permissions

Solution:

{
    data: {
        content: "chmod +x script.sh && ./script.sh",
        flags: { executionPolicyBypass: true }
    }
}

"Process timeout"¶

Cause: Command taking too long

Solution:

{
    data: {
        content: "long-running-command",
        flags: { exitOnError: true }
    }
}

"Exit code non-zero"¶

Cause: Command failed

Solution:

{
    data: {
        flags: { exitOnError: true }
    }
}

Debugging Tips¶

Enable streaming:

{
    data: {
        streamOutput: true
    }
}

Check exit codes:

// CLI nodes return exit code in result
// Check for non-zero exit codes

Log execution:

{
    data: {
        title: 'Debug Command',
        content: 'set -x && your-command',
        streamOutput: true
    }
}

Best Practices¶

General¶

Use approval system - For dangerous commands
Validate commands - Test in safe environment first
Stream output - For long-running commands
Handle errors - Check exit codes
Use stdin carefully - Avoid command injection
Set timeouts - Prevent hanging processes
Log execution - Debug issues

Command Design¶

Keep commands simple - One command per node
Use full paths - Avoid PATH issues
Quote variables - Prevent word splitting
Use built-ins - When possible
Test commands - Verify before workflow

Security¶

Never trust input - Validate all inputs
Use safe mode - For user-provided commands
Restrict file access - Use appropriate permissions
Monitor execution - Log all commands
Use approval - For dangerous operations

Performance¶

Use appropriate shell - Match to platform
Minimize I/O - Reduce file operations
Parallel execution - Use workflow parallelism
Stream output - For long-running commands
Limit output - Use head/tail/grep

Advanced Configuration¶

Custom Shell Configuration¶

{
    data: {
        content: 'source ~/.bashrc && your-command',
        shell: 'bash',
        flags: {
            noProfile: false  // Load profile
        }
    }
}

Timeout Configuration¶

{
    data: {
        content: 'long-running-command',
        flags: {
            exitOnError: true  // Fail on timeout
        }
    }
}

Resource Limits¶

{
    data: {
        content: 'resource-intensive-command',
        env: {
            static: {
                NODE_OPTIONS: '--max-old-space-size=4096'
            }
        }
    }
}

Parallel Execution¶

// Use workflow parallelism
// Set concurrency limits in workflow settings
{
    data: {
        content: 'build-command',
        streamOutput: true
    }
}

Node Types Reference - CLI node details
Protocol Reference - Message protocol
Events Reference - Event system
Integrations Overview - All integrations
Advanced Workflows - Advanced patterns