Infrastructure guide
Workflow Manager Guide
Batch command execution with hybrid conditional logic, per-step timeouts and logged runs, backed by 122 bundled workflow profiles. This guide covers building, running, and composing workflows.
Workflows
Automation
Conditional logic
Profiles
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 | 10.0.3 (build 75) |
| Build Date | Not disclosed |
| Rust Version | 1.82.0 |
| File Size | 8.7MB |
| Author | Warith Al Maawali |
| License | Proprietary |
| Category | Infrastructure & Management |
| Description | Workflow manager for batch command execution with conditional logic |
| JSON Data | View Raw JSON |
SHA256 Checksum
e407d2ad9248e3b2a640089f5602ae5a0b051f0f5b97f81625dc0d63ecb160eb
Key Features
Workflow Management
| Feature | Description |
|---|---|
| Template-based Workflows | Create reusable workflow templates for batch operations |
| Conditional Execution | Execution-gate system: steps run only when a named condition variant passes (IfSuccess, IfFail, IfContains, IfRegex, IfJsonPathEquals, etc.) |
| Batch Processing | Execute multiple commands one after another, each with its own timeout |
| State Tracking | Maintain workflow execution state and log every run |
| Pause Controls | Interactive pause steps with user confirmation |
| Workflow Composition | Include external profiles as steps for modular reuse |
| 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 | Conditions decide what runs after a failed step; the runner never retries a step automatically |
| Flexibility | Multiple condition types allow precise control flow |
| Auditability | Every run is logged as plain text through logs-hook in logs/workflow-manager-log.log |
| 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 one command step per invocation; repeat for additional sequential steps
workflow-manager add my-workflow "sudo ip-fetch"
# 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 the run through logs-hook
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","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","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
# Verbose output (show prints the template, not a run 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
# Check what you are about to delete first: delete has no --confirm and no prompt
workflow-manager show my-workflow
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 Variants
Each step carries exactly one Condition variant which acts as an execution gate, the step runs only if the named condition passes against the previous step's result. Variants are mutually exclusive per step; they are not evaluated in a sequence.
| Category | Variants |
|---|---|
| Exit code | IfSuccess, IfFail |
| Text matching | IfContains, IfNotContains, IfEquals, IfNotRegex |
| Regex | IfRegex |
| JSON | IfJsonPathEquals |
| Probe / state / expression | IfProbe, IfState, IfExpression |
| Unconditional | Always (default) |
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 'online-auth check-login --json' --timeout 30
workflow-manager add auth-check 'echo Session valid' --if-json-path '$.data.is_logged_in=true'
# 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","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..."
# }
Execution Logs
Runs are logged as plain text through logs-hook, one line per event:
# View execution logs
cat /opt/kodachi/dashboard/hooks/logs/workflow-manager-log.log
# Each line: timestamp, [LEVEL], workflow-manager: message
Authentication and Permissions
Authentication Requirements
| Operation | Requires Auth | Notes |
|---|---|---|
| Template changes | Yes | create, add, pause, include, update, delete, delete-step check for an online-auth session |
| Template reading | No | list, show, state, prereq |
| Workflow Execution (run) | When the template requires it | run makes no login check of its own; a template that lists authenticated in its prerequisites is refused until you sign in |
| Workflow Steps | Varies | Individual commands within workflows may require auth (e.g., sudo online-auth) |
Authentication Required for Execution
You must authenticate with sudo online-auth authenticate before creating or changing a workflow: create, add, pause, include, update, delete and delete-step each check directly and refuse with "Authentication failed. Access denied." run needs a session only when the template lists authenticated among its prerequisites, and the steps themselves may call commands that need one. The read-only commands (list, show, state, prereq) 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: 300s, max: 3600s) |
| 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 |
| No Automatic Retries | A failed step is never re-run in a loop; conditions decide what runs next |
| Dry Run Mode | Test workflows without execution |
| Audit Trail | Every run logged as plain text through logs-hook |
| 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 Logs | 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
# Follow the workflow-manager log
tail -f /opt/kodachi/dashboard/hooks/logs/workflow-manager-log.log
# 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 'online-auth check-login --json' --timeout 30
workflow-manager add system-check 'echo Auth OK' --if-json-path '$.data.is_logged_in=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 | 10.0.3 (build 75) | 2026 | Proprietary |
| Rust Version | 1.82.0 | - | - |
| Documentation | 10.0.3 (build 75) | 2026 | © 2026 Kodachi OS |
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 the first DNS configuration step
workflow-manager add dns-testing "sudo dns-switch random" --timeout 60
# Expected: One step added to template 'dns-testing'
# Step 3: Add second DNS configuration test
workflow-manager add dns-testing 'sudo dns-switch switch --servers 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 'dns-leak test --json' -c if_success --timeout 60
# Expected: Step added
# Step 5: Add alert if the leak test reports a potential leak
workflow-manager add dns-testing 'echo "WARNING: DNS leak detected"' --if-json-path '$.data.potential_leak_detected=true'
# Expected: Step added with JSON path condition (a text match on 'leak' would also fire on "No leak")
# Step 6: Add success message if no leak (a skipped step 5 leaves the leak test as the previous result)
workflow-manager add dns-testing 'echo "SUCCESS: No DNS leak detected"' --if-json-path '$.data.potential_leak_detected=false'
# Expected: Step added with JSON path 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/logs/workflow-manager-log.log | tail -20
# Expected: the latest plain-text log lines for the run
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.
Bundled profiles
Kodachi ships 122 canonical workflow profiles in /opt/kodachi/dashboard/hooks/config/profiles/. Reference any of them from your own template with workflow-manager include <workflow> <profile-id>, or copy one as a starting point before editing.
# 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": "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 the include step
workflow-manager include complete-setup 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
workflow-manager include complete-setup 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: every available state with its current value
# 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