Workflow Manager
File Information
| Property | Value |
|---|---|
| Binary Name | workflow-manager |
| Version | 9.0.1 |
| File Size | 3.0MB |
| Author | Warith Al Maawali |
| License | Proprietary |
| Category | System Service |
| Description | Workflow manager for batch command execution with conditional logic |
| JSON Data | View Raw JSON |
SHA256 Checksum
Key Features
Workflow Management
| Feature | Description |
|---|---|
| Template-based Workflows | Create reusable workflow templates for batch operations |
| Conditional Execution | Hybrid conditional system: success/fail + pattern matching + JSON path evaluation |
| Batch Processing | Execute multiple commands sequentially with retry logic |
| State Tracking | Maintain workflow execution state and telemetry data |
| Pause Controls | Interactive pause steps with user confirmation |
| Concurrent Execution | Support for parallel command execution within workflows |
| Pattern Matching | Regex and substring matching for conditional logic |
| JSON Path Support | Evaluate JSON output with path expressions for advanced conditions |
Why Workflow Manager is Critical
| Benefit | Description |
|---|---|
| Automation | Automate complex multi-step operations with single commands |
| Reliability | Built-in retry logic and error handling ensures operation completion |
| Flexibility | Multiple condition types allow precise control flow |
| Auditability | Comprehensive telemetry and logging in JSONL format |
| Safety | Dry-run mode and timeouts prevent unintended operations |
| Efficiency | Batch command chaining reduces manual intervention |
TL;DR - Essential Commands
# Create a new workflow template
workflow-manager create my-workflow
# Add commands to workflow (comma-separated for multiple)
workflow-manager add my-workflow "sudo ip-fetch","sudo online-auth check-login","ip addr show"
# Run workflow with all steps
sudo workflow-manager run my-workflow
# Test workflow without execution
sudo workflow-manager run my-workflow --dry-run
# List all workflow templates
workflow-manager list
# Show workflow details
workflow-manager show my-workflow
# Delete workflow template
workflow-manager delete my-workflow
Understanding Workflow Management
How Workflow Manager Works
Workflow Manager provides template-based batch command execution with conditional logic:
# Create workflow template
workflow-manager create diagnostics
# Add steps with conditions
workflow-manager add diagnostics './health-control net-check' --timeout 30
workflow-manager add diagnostics './tor-switch status' -c if_success
workflow-manager add diagnostics './dns-leak test' -c if_success
# Execute workflow
sudo workflow-manager run diagnostics
# What it does:
# - Runs health-control net-check (30s timeout)
# - If successful, runs tor-switch status
# - If that succeeds, runs dns-leak test
# - Logs all execution telemetry
Template Management
Create and manage workflow templates:
# Create new template
workflow-manager create backup-workflow
# Create with description
workflow-manager create backup-workflow --description 'Daily backup routine'
# List all templates
workflow-manager list
# Show template details
workflow-manager show backup-workflow
# Delete template
workflow-manager delete backup-workflow
Adding Commands
Add commands to workflows individually or in batches:
# Single command
workflow-manager add my-workflow 'echo Hello World'
# Multiple commands at once (comma-separated)
workflow-manager add w1 "sudo ip-fetch","sudo online-auth check-login","ip addr show"
# With timeout
workflow-manager add my-workflow 'tar czf backup.tar.gz /data' --timeout 600
# With condition
workflow-manager add my-workflow 'cleanup.sh' --condition if_success
# With pattern matching
workflow-manager add my-workflow 'notify-admin.sh' --if-contains 'error'
# With JSON path condition
workflow-manager add my-workflow 'handle-connected.sh' --if-json-path '$.status="connected"'
Command Reference (9 Commands)
1. create - Create Workflow Template
Creates a new empty workflow template.
# Basic usage
workflow-manager create my-workflow
# With description
workflow-manager create backup-workflow --description 'Daily backup routine'
# JSON output
workflow-manager create diagnostics --json
Purpose: Initialize new workflow templates for batch operations.
2. add - Add Command Steps
Adds one or more command steps to a workflow template.
# Single command
workflow-manager add my-workflow 'echo Hello World'
# Multiple commands (comma-separated)
workflow-manager add w1 "sudo ip-fetch","sudo online-auth check-login","ip addr show"
# With timeout (seconds)
workflow-manager add my-workflow 'long-operation.sh' --timeout 600
# With condition
workflow-manager add my-workflow 'deploy.sh' -c if_success
workflow-manager add my-workflow 'rollback.sh' -c if_fail
# With pattern matching
workflow-manager add my-workflow 'alert.sh' --if-contains 'error'
workflow-manager add my-workflow 'continue.sh' --if-not-contains 'error'
# With exact match
workflow-manager add my-workflow 'handle-done.sh' --if-equals 'ready'
# With regex
workflow-manager add my-workflow 'process.sh' --if-regex '^status: (ok|success)$'
# With JSON path
workflow-manager add my-workflow 'connected.sh' --if-json-path '$.status="connected"'
workflow-manager add my-workflow 'finland.sh' --if-json-path '$.data.records[0].country_name="Finland"'
Purpose: Build workflow steps with flexible conditional logic.
3. pause - Add Pause Step
Adds an interactive pause point in the workflow.
# Basic pause
workflow-manager pause my-workflow --message 'Review results before continuing'
# Conditional pause
workflow-manager pause backup --message 'Verify backup integrity' -c if_success
# JSON output
workflow-manager pause my-workflow --message 'Check status' --json
Purpose: Add manual checkpoints for user review during workflow execution.
4. list - List All Workflows
Shows all available workflow templates.
# List workflows
workflow-manager list
# JSON output
workflow-manager list --json
# With details
workflow-manager list --verbose
Purpose: View all configured workflow templates.
5. show - Display Workflow Details
Shows the complete structure and steps of a workflow template.
# Show workflow
workflow-manager show my-workflow
# JSON output
workflow-manager show my-workflow --json
# With execution history
workflow-manager show my-workflow --verbose
Purpose: Inspect workflow configuration and step details.
6. run - Execute Workflow
Executes all commands in a workflow sequentially.
# Run workflow
sudo workflow-manager run my-workflow
# Dry run (test without execution)
sudo workflow-manager run my-workflow --dry-run
# With verbose output
sudo workflow-manager run my-workflow --verbose
# JSON output
sudo workflow-manager run my-workflow --json
Purpose: Execute workflow templates with conditional logic evaluation.
Note: Requires sudo when workflow contains system commands.
7. update - Update Workflow Step
Changes an existing step in a workflow template.
# Update command
workflow-manager update my-workflow 1 'echo Updated Command'
# Update with new timeout
workflow-manager update my-workflow 1 'echo Updated' --timeout 300
# Update condition
workflow-manager update my-workflow 2 'backup.sh' -c if_success
# JSON output
workflow-manager update my-workflow 1 'new command' --json
Purpose: Modify existing workflow steps without recreating the template.
8. delete-step - Remove Workflow Step
Deletes a specific step from a workflow template.
# Delete step by ID
workflow-manager delete-step my-workflow 2
# JSON output
workflow-manager delete-step my-workflow 3 --json
Purpose: Remove individual steps from workflows. Step IDs are renumbered after deletion.
9. delete - Remove Workflow Template
Permanently deletes an entire workflow template.
# Delete workflow
workflow-manager delete my-workflow
# JSON output
workflow-manager delete backup-workflow --json
# With confirmation
workflow-manager delete my-workflow --confirm
Purpose: Remove entire workflow templates from the system.
Conditional Logic System
Condition Types
| Condition | Flag | Description | Example |
|---|---|---|---|
| Always | -c always |
Always execute (default) | Always runs regardless of previous step |
| If Success | -c if_success |
Execute if previous step succeeded (exit code 0) | Deploy after successful build |
| If Fail | -c if_fail |
Execute if previous step failed (exit code ≠ 0) | Rollback after failed deployment |
| If Contains | --if-contains 'TEXT' |
Execute if output contains substring | Run alert if output has 'error' |
| If Not Contains | --if-not-contains 'TEXT' |
Execute if output does NOT contain substring | Continue if no 'error' found |
| If Equals | --if-equals 'TEXT' |
Execute if output exactly equals value | Check for exact 'ready' output |
| If Regex | --if-regex 'PATTERN' |
Execute if output matches regex pattern | Match status patterns |
| If JSON Path | --if-json-path 'PATH=VALUE' |
Execute if JSON field matches value | Evaluate JSON responses |
JSON Path Examples
# Simple field check
workflow-manager add w1 'step.sh' --if-json-path '$.status="connected"'
# Array indexing
workflow-manager add w1 'step.sh' --if-json-path '$.data.records[0].country_name="Finland"'
# Nested object with array
workflow-manager add w1 'step.sh' --if-json-path '$.data.records[0].connection_status.connection_type="Proxy"'
# Boolean field
workflow-manager add w1 'step.sh' --if-json-path '$.ip_connectivity=true'
# Number field
workflow-manager add w1 'step.sh' --if-json-path '$.status_code=2'
Condition Evaluation Order
- Exit Code Check (if_success/if_fail)
- Pattern Matching (contains/not-contains/equals)
- Regex Matching (if-regex)
- JSON Path Evaluation (if-json-path)
Real-World Kodachi Workflows
IP Verification Workflow
# Create workflow
workflow-manager create ip-verify
# Add steps
workflow-manager add ip-verify 'sudo ip-fetch --json' --timeout 60
workflow-manager add ip-verify 'echo Finland detected' --if-json-path '$.data.records[0].country_name="Finland"'
# Run workflow
sudo workflow-manager run ip-verify
Authentication Check Workflow
# Create workflow
workflow-manager create auth-check
# Add steps
workflow-manager add auth-check 'sudo online-auth check-login --json' --timeout 30
workflow-manager add auth-check 'echo Session valid' --if-contains 'valid'
# Run workflow
sudo workflow-manager run auth-check
System Health Audit Workflow
# Create workflow
workflow-manager create health-audit
# Add steps with cascading conditions
workflow-manager add health-audit 'sudo health-control net-check --json' --timeout 60
workflow-manager add health-audit 'echo Network online' --if-json-path '$.ip_connectivity=true'
workflow-manager add health-audit 'sudo routing-switch status --json' -c if_success --timeout 30
# Run workflow
sudo workflow-manager run health-audit
Tor Verification Workflow
# Create workflow
workflow-manager create tor-verify
# Add steps
workflow-manager add tor-verify 'sudo tor-switch get-tor-status --json' --timeout 30
workflow-manager add tor-verify 'echo Tor responding' --if-json-path '$.data.is_responding=true'
# Run workflow
sudo workflow-manager run tor-verify
Backup Workflow with Pause
# Create complete backup workflow
workflow-manager create backup
workflow-manager add backup 'tar czf backup.tar.gz /data'
workflow-manager pause backup --message 'Check backup size' -c if_success
workflow-manager add backup 'rsync backup.tar.gz remote:/backups' -c if_success
workflow-manager add backup 'rm backup.tar.gz' -c if_success
# Execute with manual checkpoint
sudo workflow-manager run backup
Efficient Batch Building
Command Chaining
Build complete workflows quickly by chaining commands with &&:
# Create and populate workflow in one line
workflow-manager create tor-recovery && \
workflow-manager add tor-recovery './routing-switch recover internet' --timeout 60 && \
workflow-manager add tor-recovery './health-control net-check' -c if_success && \
workflow-manager add tor-recovery './tor-switch start' -c if_success --timeout 120
# Multi-step diagnostics
workflow-manager add diagnostics './health-control net-check' --timeout 30 && \
workflow-manager add diagnostics './tor-switch status' -c if_success && \
workflow-manager add diagnostics './dns-leak test' -c if_success && \
workflow-manager add diagnostics './integrity-check verify' -c if_success
Comma-Separated Batch Addition
Add multiple steps in a single command:
# Add 3 steps at once
workflow-manager add w1 "sudo ip-fetch","sudo online-auth check-login","ip addr show"
# Create diagnostic workflow with multiple steps
workflow-manager add diagnostics "./health-control net-check","./tor-switch status","./dns-leak test"
Output Formats
Standard Output
workflow-manager list
# Output:
# Workflow Templates (3 total)
# - my-workflow (5 steps)
# - diagnostics (4 steps)
# - backup (4 steps)
JSON Output
workflow-manager show my-workflow --json
# Output:
# {
# "data": {
# "name": "my-workflow",
# "description": "",
# "steps": [...]
# },
# "status": "success",
# "timestamp": "2025-10-08T..."
# }
Telemetry Logs
Execution logs are saved in JSONL format:
# View execution logs
cat /home/kodachi/k900/dashboard/hooks/workflow-manager/telemetry.jsonl
# Each line is a JSON object with:
# - workflow_name
# - step_id
# - command
# - exit_code
# - duration
# - timestamp
# - output
Authentication and Permissions
Authentication Requirements
| Operation | Requires Auth | Notes |
|---|---|---|
| Template Management | No | create, add, pause, list, show, delete, update, delete-step |
| Workflow Execution (run) | Yes | The ONLY command requiring authentication |
| Workflow Steps | Varies | Individual commands within workflows may require auth (e.g., sudo online-auth) |
Authentication Required for Execution
The run command is the ONLY workflow-manager command that requires authentication. You must authenticate using sudo online-auth authenticate before executing workflows with the run command. All other commands (template management, viewing, editing) work without authentication.
Sudo Requirements
| Operation | Requires Sudo | Reason |
|---|---|---|
| Template Management | No | create, add, pause, list, show, delete, update |
| Workflow Execution | Yes (usually) | Most workflows contain system commands requiring sudo |
| Dry Run | Yes (usually) | To validate commands requiring sudo |
Best Practice: Always use sudo when running workflows that contain system-level commands.
Settings Discovery
View configurable settings and examples:
# Display all settings
workflow-manager -e
# Settings in JSON format
workflow-manager -e --json
# Human-readable JSON
workflow-manager -e --json-human
# View specific setting categories
workflow-manager -e | grep -A 10 "Template Management"
Common Workflows
Template Management
# Create template
workflow-manager create my-workflow --description 'My custom workflow'
# List all templates
workflow-manager list --json
# Show template structure
workflow-manager show my-workflow
# Delete template
workflow-manager delete my-workflow
Step Management
# Add single step
workflow-manager add my-workflow 'echo Hello'
# Add multiple steps
workflow-manager add my-workflow "cmd1","cmd2","cmd3"
# Update step
workflow-manager update my-workflow 1 'echo Updated'
# Delete step
workflow-manager delete-step my-workflow 2
# Add pause
workflow-manager pause my-workflow --message 'Check status'
Workflow Execution
# Test workflow (dry run)
sudo workflow-manager run my-workflow --dry-run
# Execute workflow
sudo workflow-manager run my-workflow
# Verbose execution
sudo workflow-manager run my-workflow --verbose
# JSON output
sudo workflow-manager run my-workflow --json
Performance Metrics
| Metric | Value | Description |
|---|---|---|
| Template Limit | Unlimited | No hard limit on workflow templates |
| Steps per Workflow | Unlimited | No hard limit on steps per template |
| Execution Timeout | Configurable | Per-step timeout (default: 30s, max: 600s) |
| Condition Evaluation | < 10ms | Time to evaluate conditions |
| JSON Parsing | < 50ms | JSON path evaluation overhead |
| Telemetry Overhead | < 5% | Performance impact of logging |
Security Features
Built-in Security
| Feature | Description |
|---|---|
| Execution Containment | Workflows run within execution folder boundaries |
| Timeout Protection | Prevents runaway commands with configurable timeouts |
| Retry Limits | Prevents infinite retry loops |
| Dry Run Mode | Test workflows without execution |
| Audit Trail | Complete telemetry logging in JSONL format |
| Working Directory Control | Explicit control over command execution context |
Security Best Practices
| Practice | Description |
|---|---|
| Validate Workflows | Always test with --dry-run before production execution |
| Limit Timeouts | Set appropriate timeouts to prevent resource exhaustion |
| Review Templates | Regularly audit workflow templates for security |
| Secure Storage | Store workflow templates in secure locations |
| Minimize Privileges | Only use sudo when absolutely necessary |
| Monitor Telemetry | Review execution logs for anomalies |
Troubleshooting
Common Issues
| Issue | Solution | Prevention |
|---|---|---|
| Step fails immediately | Check command syntax, path, and permissions | Use --dry-run to validate |
| Timeout errors | Increase timeout with --timeout flag | Set realistic timeouts based on operation |
| Condition not evaluating | Check output format (JSON/text) and condition syntax | Test conditions with single-step workflows |
| Template not found | Verify template name with workflow-manager list |
Use exact template names |
| Permission denied | Run with sudo for system commands | Check command requirements |
| JSON path fails | Ensure previous output is valid JSON | Validate JSON output format |
Diagnostic Commands
# List all workflows
workflow-manager list
# Show workflow details
workflow-manager show my-workflow --verbose
# Test workflow without execution
sudo workflow-manager run my-workflow --dry-run --verbose
# Check telemetry logs
tail -f /home/kodachi/k900/dashboard/hooks/workflow-manager/telemetry.jsonl
# Verify workflow syntax
workflow-manager show my-workflow --json | jq '.'
Integration with Other Services
Service Interactions
| Service | Integration Type | Purpose |
|---|---|---|
| logs-hook | Automatic | All workflow operations logged centrally |
| online-auth | Optional | Workflows can call authentication commands |
| health-control | Optional | Workflows can perform health checks |
| tor-switch | Optional | Workflows can manage Tor operations |
| routing-switch | Optional | Workflows can control network routing |
| ip-fetch | Optional | Workflows can fetch IP information |
Example Integration Workflow
# Complete system check workflow
workflow-manager create system-check
# Add integrated steps
workflow-manager add system-check 'sudo online-auth check-login --json' --timeout 30
workflow-manager add system-check 'echo Auth OK' --if-json-path '$.data.authenticated=true'
workflow-manager add system-check 'sudo health-control net-check --json' -c if_success --timeout 60
workflow-manager add system-check 'echo Network OK' --if-json-path '$.ip_connectivity=true'
workflow-manager add system-check 'sudo tor-switch get-tor-status --json' -c if_success --timeout 30
workflow-manager add system-check 'echo Tor OK' --if-json-path '$.data.is_responding=true'
workflow-manager add system-check 'sudo ip-fetch --json' -c if_success --timeout 60
workflow-manager add system-check 'echo IP OK' -c if_success
# Execute complete check
sudo workflow-manager run system-check
Advanced Features
Pattern Matching
# Substring matching (case-sensitive)
workflow-manager add w1 'alert.sh' --if-contains 'error'
workflow-manager add w1 'continue.sh' --if-not-contains 'error'
# Exact match (trimmed)
workflow-manager add w1 'done.sh' --if-equals 'ready'
# Regex matching (full syntax)
workflow-manager add w1 'process.sh' --if-regex '^status: (ok|success)$'
workflow-manager add w1 'handle.sh' --if-regex '^\d{3}\s+OK$'
Complex JSON Path Evaluation
# Nested objects
workflow-manager add w1 'step.sh' --if-json-path '$.data.user.status="active"'
# Array indexing
workflow-manager add w1 'step.sh' --if-json-path '$.items[0].name="test"'
workflow-manager add w1 'step.sh' --if-json-path '$.records[2].value=100'
# Deep nesting with arrays
workflow-manager add w1 'step.sh' --if-json-path '$.data.records[0].details.type="proxy"'
# Multiple conditions (use separate steps)
workflow-manager add w1 'step1.sh' --if-json-path '$.status="ok"'
workflow-manager add w1 'step2.sh' --if-json-path '$.code=200' -c if_success
Working Directory Management
# All commands execute in workflow-manager's current directory
# To change working directory, use cd in the command:
workflow-manager add w1 'cd /tmp && ./script.sh'
# Or use absolute paths
workflow-manager add w1 '/home/user/scripts/task.sh'
# Chain directory changes
workflow-manager add w1 'cd /data && tar czf backup.tar.gz .'
System Information
| Component | Version | Build Date | License |
|---|---|---|---|
| workflow-manager | 9.0.1 | 2025-10-08 | Proprietary |
| Rust Version | 1.82.0 | - | - |
| Documentation | 9.0.1 | 2025-10-08 | © 2025 Linux Kodachi |