Skip to main content

Running Workflows

Basic Command Line Usage​

# Run workflow with default entry point
nexroo run path/to/your/file.json

# Run with specific entry point
nexroo run path/to/your/file.json [entrypoint_id]

# Using poetry
poetry run nexroo-engine .\config.json [entrypoint_id]

Command Line Options​

Arguments:

  • json_path - Path to the JSON configuration file (required)
  • entrypoint_id - Optional entrypoint ID (defaults to 'default' if not specified)

Options:

  • -v, --verbose - Enable verbose logging for detailed execution info
  • --mock - Run in mock mode using mock handlers instead of real addons
  • --dry-run - Run in dry run mode (simulate execution without running actions)
  • --mock-config PATH - Path to mock configuration file (JSON format)
  • --payload JSON - JSON payload to pass as input data to the workflow
  • --payload-file PATH - Path to JSON file containing payload data

Execution Modes​

Production Mode (Default)​

Uses real addons and executes actual actions:

nexroo run workflow.json

Mock Mode​

Uses mock handlers for testing and development:

nexroo run workflow.json --mock

Dry Run Mode​

Analyzes workflow structure without execution:

nexroo run workflow.json --dry-run

Verbose Mode​

Enables detailed logging for debugging:

nexroo run workflow.json --verbose

Payload Usage​

Pass input data to workflows using JSON payload with content and type structure:

Payload Structure: The system now uses a standardized payload format:

{
  "content": {your_actual_data},
  "type": "content_type",
  "metadata": {optional_metadata}
}

Linux/macOS/WSL:

# Structured payload with content and type
nexroo run workflow.json --payload '{"content": {"message": "Hello world", "priority": "high"}, "type": "application/json"}'

# Text content
nexroo run workflow.json --payload '{"content": "Hello world", "type": "text/plain"}'

# Image payload (base64 encoded)
nexroo run workflow.json --payload '{"content": "iVBORw0KGgoAAAANSUhEUgA...", "type": "image/png"}'

Windows PowerShell:

# Structured payload
nexroo run workflow.json --payload='{"content": {"message": "Hello world", "priority": "high"}, "type": "application/json"}'

# Text content
nexroo run workflow.json --payload='{"content": "Hello world", "type": "text/plain"}'

# Complex nested content
nexroo run workflow.json --payload='{"content": {"request": {"data": {"items": [{"name": "item1"}]}}}, "type": "application/json"}'

Using Payload Files (Recommended for Complex Payloads): For complex payloads or to avoid shell escaping issues, use JSON files:

Create a payload file (e.g., my-payload.json):

{
  "content": {
    "message": "Hello world",
    "priority": "high",
    "data": {
      "items": [
        {"name": "item1", "value": 100},
        {"name": "item2", "value": 200}
      ]
    }
  },
  "type": "application/json",
  "metadata": {
    "source": "api",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Then reference it in the command:

# All platforms - no quoting issues
nexroo run workflow.json --payload-file my-payload.json

# With other options
nexroo run workflow.json --payload-file my-payload.json --mock --verbose

Legacy Format Support: For backward compatibility, the system also accepts raw payloads and will auto-detect content types:

# Legacy format - auto-detects as JSON
nexroo run workflow.json --payload '{"user_input": "Hello world", "priority": "high"}'

Combined Options​

# Dry run with verbose output
nexroo run workflow.json --dry-run --verbose

# Mock mode with custom configuration
nexroo run workflow.json --mock --mock-config custom-mocks.json

# Production with payload file (recommended)
nexroo run workflow.json --payload-file payload.json

# Production with inline payload
nexroo run workflow.json --payload '{"question": "What is AI?", "context": "education"}'