Workflow Manager
Documentation Navigation
This page is scenario-first (operational workflows, real run order, and troubleshooting). For the full autogenerated command/flag catalog, use the CLI Reference.
File Information
| Property | Value |
|---|---|
| Binary Name | workflow-manager |
| Version | 9.0.1 |
| Build Date | 2026-03-12T22:18:25.378571805Z |
| Rust Version | 1.82.0 |
| File Size | 3.4MB |
| 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 tor-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 tor-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 (12 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.
10. include - Include External Workflow
Adds an include step to a workflow template that references another profile.
# Include another workflow profile
workflow-manager include my-workflow other-profile
# JSON output
workflow-manager include my-workflow shared-steps --json
Purpose: Compose workflows by including steps from other workflow templates, enabling reusable modular workflow design.
11. state - Query System State
Queries the current system state for use in prerequisite validation.
# Check all system states
workflow-manager state
# Check specific state
workflow-manager state online
workflow-manager state authenticated
# JSON output
workflow-manager state --json
Purpose: Inspect system state values used by workflow prerequisites.
12. prereq - Validate Prerequisites
Validates that workflow prerequisites are met before execution.
# Validate prerequisites for a workflow
workflow-manager prereq check my-workflow
# JSON output
workflow-manager prereq check my-workflow --json
Purpose: Check if system state requirements are satisfied before running a workflow.
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' --timeout 60 && \
workflow-manager add tor-recovery 'health-control net-check' -c if_success && \
workflow-manager add tor-recovery 'tor-switch start-tor' -c if_success --timeout 120
# Multi-step diagnostics
workflow-manager add diagnostics 'health-control net-check' --timeout 30 && \
workflow-manager add diagnostics 'tor-switch tor-status' -c if_success && \
workflow-manager add diagnostics 'dns-leak test' -c if_success && \
workflow-manager add diagnostics 'integrity-check check-all' -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 tor-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 /opt/kodachi/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 /opt/kodachi/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 |
Scenario 1: Creating Your First Security Health Workflow
Quick setup to create a workflow that validates system security and network connectivity.
# Step 1: Create the workflow template
workflow-manager create security-health
# Expected: Template 'security-health' created successfully
# Step 2: Add network connectivity check with 60s timeout
workflow-manager add security-health 'sudo health-control net-check --json' --timeout 60
# Expected: Step 1 added to template 'security-health'
# Step 3: Add IP geolocation fetch only if network is online
workflow-manager add security-health 'sudo ip-fetch --json' --if-json-path '$.ip_connectivity=true' --timeout 60
# Expected: Step 2 added with JSON path condition
# Step 4: Add security score check if IP fetch succeeded
workflow-manager add security-health 'sudo health-control security-score' -c if_success --timeout 60
# Expected: Step 3 added with if_success condition
# Step 5: Run the complete workflow
sudo workflow-manager run security-health
# Expected: All steps execute in sequence with condition evaluation
# Step 6: View workflow structure
workflow-manager show security-health
# Expected: Displays all 3 steps with conditions and timeouts
Cross-binary workflow: workflow-manager + health-control + ip-fetch
When to run: Daily system health validation, before connecting to VPN/Tor, or after system changes.
Scenario 2: Multi-Stage Recovery with Conditional Pauses
Build a recovery workflow that requires user confirmation between stages.
# Step 1: Create recovery workflow
workflow-manager create network-recovery
# Expected: Template 'network-recovery' created successfully
# Step 2: Add initial routing recovery
workflow-manager add network-recovery 'sudo routing-switch recover' --timeout 60
# Expected: Step 1 added
# Step 3: Add pause for user verification
workflow-manager pause network-recovery --message 'Verify internet connectivity before continuing' -c if_success
# Expected: Pause step added with if_success condition
# Step 4: Restart Tor if recovery succeeded
workflow-manager add network-recovery 'sudo tor-switch start-tor' -c if_success --timeout 120
# Expected: Step added with if_success condition
# Step 5: Add another pause to verify Tor status
workflow-manager pause network-recovery --message 'Check Tor status before DNS configuration' -c if_success
# Expected: Pause step added
# Step 6: Configure DNSCrypt if Tor is running
workflow-manager add network-recovery 'sudo dns-switch dnscrypt on' -c if_success --timeout 60
# Expected: Step added with if_success condition
# Step 7: Run workflow with interactive pauses
sudo workflow-manager run network-recovery
# Expected: User prompted at each pause point
# Step 8: Test without execution to verify flow
sudo workflow-manager run network-recovery --dry-run
# Expected: Dry run showing all steps and pause points
Cross-binary workflow: workflow-manager + routing-switch + tor-switch + dns-switch
When to run: Network connectivity issues, after VPN/Tor failures, or system recovery scenarios. Or Automate this with workflow-manager by removing pause steps.
Scenario 3: Batch DNS Server Testing with Conditions
Test multiple DNS configurations and verify for leaks.
# Step 1: Create DNS testing workflow
workflow-manager create dns-testing
# Expected: Template 'dns-testing' created successfully
# Step 2: Add multiple DNS switches in one command
workflow-manager add dns-testing "sudo dns-switch random","sudo dns-leak test","echo 'Random DNS tested'" --timeout 60
# Expected: 3 steps added to template 'dns-testing'
# Step 3: Add second DNS configuration test
workflow-manager add dns-testing 'sudo dns-switch set 1.1.1.1' -c if_success --timeout 30
# Expected: Step added with if_success condition
# Step 4: Verify DNS leak after setting Cloudflare DNS
workflow-manager add dns-testing 'sudo dns-leak test' -c if_success --timeout 60
# Expected: Step added
# Step 5: Add alert if leak detected (output contains 'leak')
workflow-manager add dns-testing 'echo "WARNING: DNS leak detected"' --if-contains 'leak'
# Expected: Step added with pattern matching condition
# Step 6: Add success message if no leak (output does NOT contain 'leak')
workflow-manager add dns-testing 'echo "SUCCESS: No DNS leak detected"' --if-not-contains 'leak'
# Expected: Step added with negative pattern condition
# Step 7: Run the batch test workflow
sudo workflow-manager run dns-testing
# Expected: All DNS configurations tested sequentially
# Step 8: View execution logs
cat /opt/kodachi/dashboard/hooks/workflow-manager/telemetry.jsonl | tail -20
# Expected: JSON logs showing all step executions and outputs
Cross-binary workflow: workflow-manager + dns-switch + dns-leak
When to run: Before connecting to anonymity networks, after DNS configuration changes, or periodic privacy audits.
Scenario 4: Pattern-Matching Workflows with Regex
Use regex conditions to build intelligent workflows that adapt to command output.
# Step 1: Create adaptive security workflow
workflow-manager create adaptive-security
# Expected: Template 'adaptive-security' created successfully
# Step 2: Check security score
workflow-manager add adaptive-security 'sudo health-control security-score' --timeout 60
# Expected: Step 1 added
# Step 3: Run hardening if score output matches "Low" or "Medium" pattern
workflow-manager add adaptive-security 'sudo health-control security-harden' --if-regex '^.*(Low|Medium).*$' --timeout 120
# Expected: Step added with regex condition
# Step 4: Skip if 4+ HARDENED components found (inverse regex counting)
workflow-manager add adaptive-security 'echo "Already hardened - skipping"' --if-not-regex 'HARDENED.*HARDENED.*HARDENED.*HARDENED'
# Expected: Step added with if_not_regex condition
# Step 5: Re-check security score after hardening
workflow-manager add adaptive-security 'sudo health-control security-score' -c if_success --timeout 60
# Expected: Step added
# Step 6: Success message if score is "High" or "Critical"
workflow-manager add adaptive-security 'echo "✓ Security hardening complete"' --if-regex '^.*(High|Critical).*$'
# Expected: Step added with regex pattern
# Step 7: Run the adaptive workflow
sudo workflow-manager run adaptive-security
# Expected: Steps execute based on regex evaluation
# Step 8: Verify workflow with dry run
sudo workflow-manager run adaptive-security --dry-run --verbose
# Expected: Shows which steps would execute based on conditions
Cross-binary workflow: workflow-manager + health-control
When to run: Automated security audits, adaptive threat response, or scheduled system hardening tasks.
Scenario 5: JSON Path Conditional Step Execution
Build workflows that evaluate structured JSON output for precise control flow.
# Step 1: Create IP verification workflow
workflow-manager create ip-verification
# Expected: Template 'ip-verification' created successfully
# Step 2: Fetch IP geolocation data as JSON
workflow-manager add ip-verification 'sudo ip-fetch --json' --timeout 60
# Expected: Step 1 added
# Step 3: Check if country is Finland using JSON path
workflow-manager add ip-verification 'echo "✓ Finland VPN detected"' --if-json-path '$.data.records[0].country_name="Finland"'
# Expected: Step added with JSON path array indexing
# Step 4: Check if connection type is Proxy
workflow-manager add ip-verification 'echo "✓ Proxy connection active"' --if-json-path '$.data.records[0].connection_status.connection_type="Proxy"'
# Expected: Step added with nested JSON path
# Step 5: Verify IP connectivity boolean field
workflow-manager add ip-verification 'echo "✓ Internet connectivity confirmed"' --if-json-path '$.ip_connectivity=true'
# Expected: Step added with boolean JSON path
# Step 6: Check Tor status using JSON boolean
workflow-manager add ip-verification 'sudo tor-switch get-tor-status --json' -c if_success --timeout 30
# Expected: Step added
# Step 7: Verify Tor is responding
workflow-manager add ip-verification 'echo "✓ Tor daemon responding"' --if-json-path '$.data.is_responding=true'
# Expected: Step added with JSON boolean condition
# Step 8: Run the JSON-driven workflow
sudo workflow-manager run ip-verification
# Expected: Steps execute based on JSON field evaluation
Cross-binary workflow: workflow-manager + ip-fetch + tor-switch
When to run: VPN endpoint verification, Tor status validation, or automated connection testing.
Scenario 6: Reusable Workflow Includes/Profiles
Compose complex workflows from reusable profile components.
# Step 1: Create base authentication check profile (manual JSON edit required)
# File: /opt/kodachi/dashboard/hooks/config/profiles/base-auth-check.json
# Content: {"id": "base-auth-check", "steps": [{"cmd": "sudo online-auth check-login --json", "timeout": 30}]}
# Expected: Profile file created
# Step 2: Create main workflow that includes the profile
workflow-manager create complete-setup
# Expected: Template 'complete-setup' created successfully
# Step 3: Add include step (manual JSON edit required)
# Edit complete-setup.json to add: {"type": "include", "profile": "base-auth-check"}
# Expected: Include step references base-auth-check profile
# Step 4: Add network check after authentication
workflow-manager add complete-setup 'sudo health-control net-check --json' --timeout 60
# Expected: Step added
# Step 5: Add Tor startup with hardening
workflow-manager add complete-setup 'sudo tor-switch start-tor' -c if_success --timeout 120
# Expected: Step added
# Step 6: Include another reusable profile for DNS setup (manual edit)
# Edit complete-setup.json to add: {"type": "include", "profile": "base-dnscrypt-setup"}
# Expected: Include step references DNS profile
# Step 7: Show final workflow structure
workflow-manager show complete-setup --json
# Expected: Displays workflow with include steps
# Step 8: Run the composite workflow
sudo workflow-manager run complete-setup
# Expected: All profiles executed in sequence
Cross-binary workflow: workflow-manager + online-auth + health-control + tor-switch
When to run: Complete system setup, reproducible configuration workflows, or modular automation tasks. Or Automate this with workflow-manager by creating parametrized profiles.
Scenario 7: Prerequisite Validation Before Execution
Define system state requirements that must be met before workflow runs.
# Step 1: Create workflow with prerequisites (manual JSON edit required)
# File: /opt/kodachi/dashboard/hooks/config/profiles/tor-setup-with-prereqs.json
# Content: {"prerequisites": {"online": true, "authenticated": true, "on_failure": "abort"}, "steps": [...]}
# Expected: Profile created with prerequisite checks
# Step 2: Validate prerequisites without running workflow
workflow-manager prereq check tor-setup-with-prereqs
# Expected: ✅ All prerequisites met or ❌ Prerequisites not met
# Step 3: Check specific system state (online connectivity)
workflow-manager state online
# Expected: {"state": "online", "value": true}
# Step 4: Check authentication state
workflow-manager state authenticated
# Expected: {"state": "authenticated", "value": true/false}
# Step 5: View all available system states
workflow-manager state
# Expected: JSON with all 20 states
# Step 6: Create workflow with strict prerequisites (manual JSON edit)
# Prerequisites: authenticated=true, online=true, torrify=false
# Expected: Workflow requires auth + internet + no Tor routing
# Step 7: Attempt to run workflow without meeting prerequisites
sudo workflow-manager run tor-setup-with-prereqs
# Expected: ❌ Prerequisites not met - aborting (if prerequisites not satisfied)
# Step 8: Authenticate and run again
sudo online-auth authenticate && sudo workflow-manager run tor-setup-with-prereqs
# Expected: ✅ Prerequisites validated, workflow executes
Cross-binary workflow: workflow-manager + online-auth
When to run: Security-critical workflows requiring authentication, setup workflows requiring specific system state, or automated workflows with dependency checks.
Scenario 8: Global Settings, Kill Policy, and Timeout Management
Configure workflow-level behavior for error handling and execution control.
# Step 1: Create workflow with stop policy (manual JSON edit required)
# File: /opt/kodachi/dashboard/hooks/config/profiles/critical-workflow.json
# Content: {"global_settings": {"kill_policy": "stop", "continue_policy": false, "default_timeout": 300}}
# Expected: Workflow stops on first failure
# Step 2: Create recovery workflow with continue policy (manual JSON edit)
# File: /opt/kodachi/dashboard/hooks/config/profiles/recovery-workflow.json
# Content: {"global_settings": {"kill_policy": "continue", "continue_policy": true}}
# Expected: Workflow continues despite failures
# Step 3: Add steps with default timeout (uses global default_timeout=300s)
workflow-manager add critical-workflow 'sudo health-control net-check'
# Expected: Step uses 300s timeout from global_settings
# Step 4: Add step with custom timeout override
workflow-manager add critical-workflow 'sudo ip-fetch --json' --timeout 60
# Expected: Step uses 60s timeout, overriding global default
# Step 5: View global settings in profile
workflow-manager show critical-workflow --json
# Expected: JSON shows global_settings block
# Step 6: Create workflow with skip_remaining policy (manual JSON edit)
# Content: {"global_settings": {"kill_policy": "skip_remaining"}}
# Expected: Skip remaining steps but don't fail workflow
# Step 7: Run workflow with stop policy
sudo workflow-manager run critical-workflow
# Expected: Stops immediately on first failure (if kill_policy=stop, continue_policy=false)
# Step 8: Run workflow with continue policy
sudo workflow-manager run recovery-workflow
# Expected: Continues through all steps regardless of failures
Cross-binary workflow: workflow-manager + logs-hook (automatic logging)
When to run: Configure behavior for critical workflows (use stop policy), recovery workflows (use continue policy), or conditional workflows (use skip_remaining policy).
Related Workflows
- Security and Health Monitoring — health-control commands for workflows
- Network Routing Control — routing-switch integration
- Tor Network Management — tor-switch command surface (100+ options)
- DNS Configuration — dns-switch and dns-leak testing
- IP Geolocation — ip-fetch for verification workflows
- Authentication System — online-auth prerequisite checks
- Full CLI Reference: workflow-manager commands