workflow-manager
Workflow manager for batch command execution with conditional logic
Version: 9.0.1 | Size: 3.0MB | Author: Warith Al Maawali
License: Proprietary | Website: https://www.digi77.com
File Information
| Property | Value |
|---|---|
| Binary Name | workflow-manager |
| Version | 9.0.1 |
| Build Date | 2025-11-09T07:20:09.678807717Z |
| Rust Version | 1.82.0 |
| File Size | 3.0MB |
| JSON Data | View Raw JSON |
SHA256 Checksum
Features
| Feature | Description |
|---|---|
| Feature | Template-based workflow management |
| Feature | Conditional command execution |
| Feature | Batch processing with retry logic |
| Feature | State tracking and logging |
| Feature | Concurrent execution support |
| Feature | Pause steps with user confirmation |
| Feature | Pattern matching and regex conditions |
| Feature | JSON path expression support |
| Feature | Prerequisites validation before execution |
| Feature | System state checking and probes |
| Feature | Reusable probe functions for conditions |
Security Features
| Feature | Description |
|---|---|
| Authentication | Secure authentication with certificate pinning |
| Encryption | TLS 1.3 for all network communications |
| Inputvalidation | All inputs are validated and sanitized |
| Ratelimiting | Built-in rate limiting for network operations |
System Requirements
| Requirement | Value |
|---|---|
| OS | Linux (Debian-based) |
| Privileges | root/sudo for system operations |
| Dependencies | OpenSSL, libcurl |
Global Options
| Flag | Description |
|---|---|
-h, --help |
Print help information |
-v, --version |
Print version information |
-n, --info |
Display detailed information |
-e, --examples |
Show usage examples |
--json |
Output in JSON format |
--json-pretty |
Pretty-print JSON output with indentation |
--json-human |
Enhanced JSON output with improved formatting (like jq) |
--verbose |
Enable verbose output |
--quiet |
Suppress non-essential output |
--no-color |
Disable colored output |
--config <FILE> |
Use custom configuration file |
--timeout <SECS> |
Set timeout (default: 30) |
--retry <COUNT> |
Retry attempts (default: 3) |
Commands
Commands
create
Create a new workflow template
Usage:
add
Add a step to a workflow template
Usage:
pause
Add a pause step to a workflow template
Usage:
list
List all workflow templates
Usage:
show
Show details of a workflow template
Usage:
run
Run a workflow template
Usage:
update
Update a step in a workflow template
Usage:
delete-step
Delete a step from a workflow template
Usage:
delete
Delete an entire workflow template
Usage:
state
Query system state
Usage:
prereq
Validate workflow prerequisites
Usage:
Examples
Template Management
Create, list, view, and delete workflow templates
Creates a new empty workflow template named 'my-workflow'
Expected Output: Template 'my-workflow' created successfullyCreates a workflow with a descriptive label
Expected Output: Template 'backup-workflow' created successfullyShows all available workflow templates
Expected Output: Workflow Templates (2 total)Displays the full structure of a workflow template
Expected Output: Workflow Template: my-workflowPermanently removes a workflow template
Expected Output: Template 'my-workflow' deleted successfullyAdding Commands to Workflows
Add steps to workflows. Use comma-separated commands for multiple steps in one call, or add individually.
Adds a single command as step 1
Expected Output: Step 1 added to template 'my-workflow'Note
Single command creates one step
Add multiple steps in one command using comma separation
Expected Output: 3 steps added to template 'w1'Note
Comma-separated commands create multiple steps automatically
Create a diagnostic workflow with 3 steps at once
workflow-manager add diagnostics "./health-control net-check","./tor-switch status","./dns-leak test"
Note
All steps share the same timeout and condition settings
Adds a command with a 10-minute timeout
Expected Output: Step added with 600 second timeoutRuns only if the previous command succeeded
Expected Output: Step added with conditional executionRuns only if previous output contains 'ERROR'
Expected Output: Step added with pattern matching conditionWorkflow Execution
Run workflows and control execution behavior
Executes all commands in the workflow sequentially
Expected Output: ✅ Workflow completed: SuccessNote
Conditions are evaluated before each step
Shows what would be executed without running commands
Expected Output: Dry run: 5 steps would be executedNote
Use for testing workflows before execution
Managing Individual Steps
Update, delete, and inspect individual workflow steps
View all steps with their IDs and details
Expected Output: Step 1: echo Hello Step 2: ./backup.sh Step 3: ./cleanup.shNote
Use this to identify step IDs before updating or deleting
Remove step #2 from the workflow
Expected Output: Step 2 deleted from 'my-workflow'Note
Step IDs are renumbered after deletion
Change step #1 command and timeout
Expected Output: Step 1 updated successfullyNote
All step properties can be updated
Efficient Batch Building
Build complete workflows quickly by chaining multiple 'add' commands with &&
Create workflow and add 3 steps in one command chain
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
Note
Use && to chain commands efficiently
Add 4 diagnostic steps with conditional execution
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
Build complete backup workflow with pause and cleanup
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
Note
Mix commands and pauses for interactive workflows
Conditional Logic
All available condition types with practical examples
Always execute (default behavior, runs regardless)
Expected Output: Step added with 'always' conditionExecute only if previous step succeeded (exit code 0)
Expected Output: Step added with if_success conditionNote
Most common condition for sequential workflows
Execute only if previous step failed (exit code ≠ 0)
Expected Output: Step added with if_fail conditionNote
Useful for error recovery and rollback scenarios
Execute if previous output contains pattern "success"
Expected Output: Step added with pattern matching conditionNote
Case-sensitive - matches JSON like \"status\":\"success\"
Execute if previous output does NOT contain "errors"
Expected Output: Step added with negative pattern conditionNote
Case-sensitive - checks for absence of \"errors\" in JSON output
Execute if previous output exactly equals "ready"
Expected Output: Step added with exact match conditionNote
Exact match (case-sensitive) - output is trimmed before comparison
Execute if previous output matches regex pattern
Expected Output: Step added with regex conditionNote
Supports full regex syntax for complex matching
Execute if output does NOT match regex (counting: skip if 4+ HARDENED found)
workflow-manager add my-workflow './skip-if-hardened.sh' --if-not-regex 'HARDENED.*HARDENED.*HARDENED.*HARDENED'
Note
Inverse regex match - useful for counting occurrences. Pattern matches 4+ 'HARDENED' words.
Execute if fewer than 5 services are active (counting with regex quantifiers)
Expected Output: Step added with if_not_regex conditionNote
Uses regex quantifiers {5,} to count occurrences. Step runs if pattern does NOT match (< 5 services).
Execute if JSON field $.status equals 'connected'
Expected Output: Step added with JSON path conditionNote
Previous output must be valid JSON
Execute if JSON array element matches value
workflow-manager add my-workflow './finland-detected.sh' --if-json-path '$.data.records[0].country_name="Finland"'
Note
Supports array indexing [0], [1], etc. for nested JSON arrays
Execute if nested JSON path with array matches
workflow-manager add my-workflow './proxy-active.sh' --if-json-path '$.data.records[0].connection_status.connection_type="Proxy"'
Note
Can navigate through objects and arrays: $.path.to.array[index].field
Execute if JSON boolean field is true
Expected Output: Step added with JSON boolean conditionNote
Supports true/false without quotes
Execute if JSON number field matches
Expected Output: Step added with JSON number conditionNote
Numbers don't need quotes: =2 not ="2"
Advanced Features
Pause steps and advanced workflow management
Adds an interactive pause point in the workflow
Expected Output: Pause step added to workflowNote
User must press Enter to continue workflow execution
Conditional pause only if previous step succeeded
Expected Output: Conditional pause step addedNote
Combine pauses with conditions for smart workflows
Real-World Kodachi Workflows
Practical workflows using actual Kodachi commands
Check IP geolocation and verify country
workflow-manager create ip-verify && 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"' && workflow-manager run ip-verify
Note
Uses JSON path with array indexing to check nested geolocation data
Verify authentication and session status
workflow-manager create auth-check && workflow-manager add auth-check 'sudo online-auth check-login --json' --timeout 30 && workflow-manager add auth-check 'echo Session valid' --if-contains 'valid' && workflow-manager run auth-check
Note
Pattern matching on authentication response to confirm valid login
Complete system health and network connectivity check
workflow-manager create health-audit && 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 && workflow-manager run health-audit
Note
Combines network check with JSON boolean evaluation and cascading conditions
Verify Tor service health and responsiveness
workflow-manager create tor-verify && 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' && workflow-manager run tor-verify
Note
Checks Tor daemon status using JSON path boolean evaluation
Prerequisites
Define system state requirements that must be met before workflow execution
Prerequisites block in profile JSON - validates state before execution
# Example profile with prerequisites (edit JSON manually):
{
"prerequisites": {
"required": [
{"check": "state.online", "expect": true, "error": "Internet connection required"},
{"check": "state.torrify", "expect": false, "error": "System must not be torrified"},
{"check": "state.tor_running", "expect": true, "error": "Tor must be running"}
],
"on_failure": "abort"
}
}
Note
If prerequisites is null or not present, no prerequisite checks are performed
Validate prerequisites without running the workflow
Expected Output: ✅ All prerequisites met or ❌ Prerequisite failures listedNote
Use this to test prerequisites before execution
System State Checking
Query current system state for debugging and validation
Show all system states as JSON
Expected Output: {"online": true, "torrify": false, "dnscrypt": true, "routing_mode": "wireguard", "tor_running": true}Check specific state (online connectivity)
Expected Output: {"state": "online", "value": true}Note
20 states available: online, routing_mode, vpn_connected, dnscrypt, ipv6_disabled, dns_kodachi_managed, firewall_active, kill_switch_armed, network_hardened, disk_encrypted, security_score, torrify, tor_running, tor_dns_active, tor_verified, mac_spoofing, bluetooth_enabled, wifi_enabled, authenticated, tor_instances_count
Probe Functions
Define reusable probe functions in profiles for complex conditions
Define probes at profile level and use in step conditions
# Example profile with probes (edit JSON manually):
{
"probes": {
"harden_count": {
"probe_type": "count",
"expression": "count('harden', previous_output)",
"description": "Count 'harden' occurrences"
},
"is_hardened": {
"probe_type": "expression",
"expression": "probe('harden_count') >= 4"
}
},
"steps": [
{
"id": 2,
"cmd": "echo 'Already hardened, skipping'",
"condition": {
"type": "if_probe",
"probe": "is_hardened",
"expect": true
}
}
]
}
Note
Probe types: builtin, expression, count
Global Settings Reference
Complete reference for workflow-level configuration options and their interactions
All available global settings with default values
# Global Settings in profile JSON:
{
"global_settings": {
"kill_policy": "stop",
"continue_policy": true,
"max_log_size": 10485760,
"default_timeout": 300,
"working_dir": "."
}
}
Note
Global settings apply to entire workflow unless overridden at step level
kill_policy determines workflow behavior when steps fail
kill_policy options:
- "stop": Stop entire workflow on first failure (default, safest)
- "continue": Continue executing remaining steps even after failures
- "skip_remaining": Skip remaining steps but don't mark workflow as failed
Note
continue_policy=true overrides kill_policy completely - always continues regardless of kill_policy value
Priority logic: continue_policy overrides kill_policy
# Interaction between kill_policy and continue_policy:
If continue_policy = true:
→ Always continue (kill_policy ignored)
If continue_policy = false:
→ Check kill_policy:
- "stop" → stop workflow
- "continue" → continue workflow
- "skip_remaining" → skip remaining steps
Note
For security-critical workflows: kill_policy='stop', continue_policy=false. For recovery workflows: kill_policy='continue', continue_policy=true
default_timeout applies to all steps, working_dir sets base path for relative commands
# Timeout and working directory:
{
"global_settings": {
"default_timeout": 180,
"working_dir": "/home/kodachi/k900/dashboard/hooks"
},
"steps": [
{
"cmd": "./health-control net-check",
"timeout": 60
}
]
}
Note
max_log_size prevents runaway log growth. Logs are truncated when limit reached. Default 10MB is suitable for most workflows
Prerequisites Explained
Complete guide to workflow prerequisites - requirements that must be met before workflow runs
Prerequisites define conditions that must be true before workflow executes
# Prerequisites in profile JSON:
{
"prerequisites": {
"authenticated": true,
"online": true,
"torrify": false,
"on_failure": "abort"
}
}
Note
Prerequisites are checked BEFORE any steps execute. All must pass (AND logic)
on_failure controls behavior when prerequisites fail
on_failure options:
- "abort": Stop workflow execution immediately (default, safest)
- "skip": Skip workflow but don't fail (useful for optional workflows)
- "warn": Show warning but continue anyway (use with caution)
Note
Example: auth workflows use on_failure='abort' because running unauthenticated operations is unsafe
Real-world prerequisite patterns for different workflow types
# Common prerequisite patterns:
# Security-critical workflow:
"prerequisites": {
"authenticated": true,
"on_failure": "abort"
}
# Tor setup workflow:
"prerequisites": {
"online": true,
"torrify": false,
"on_failure": "abort"
}
# Recovery workflow (run anytime):
"prerequisites": {} # Empty - no requirements
Note
Combine prerequisites with AND logic - all must pass. For OR logic, create separate workflows
Backend implementation of prerequisite checks
# How prerequisites are checked:
authenticated: Check ~/.kodachi/auth/session file exists and valid
online: Ping check or DNS resolution test
torrify: Check routing-switch status for active Tor routing
Note
Use 'workflow-manager prereq check
Condition Types Deep Dive
Comprehensive reference for all condition types and evaluation logic
Complete list of condition types with brief descriptions
# All supported condition types:
1. "always" - Always execute (unconditional)
2. "never" - Never execute (placeholder/disabled)
3. "if_success" - Execute if previous step succeeded (exit code 0)
4. "if_fail" - Execute if previous step failed (exit code != 0)
5. "if_pattern" - Execute if previous output matches pattern (glob)
6. "if_not_pattern" - Execute if previous output does NOT match pattern
7. "if_json_path" - Execute if JSON path query returns true
8. "if_expression" - Execute if complex boolean expression evaluates true
9. "if_probe" - Execute based on probe function result
Note
Conditions are evaluated sequentially - each step checks its condition before executing
Pattern matching uses glob syntax for flexible text matching
# Pattern matching (if_pattern, if_not_pattern):
{
"condition": {
"type": "if_pattern",
"pattern": "*SUCCESS*"
}
}
Pattern syntax (glob-style):
- "*" matches any characters (wildcard)
- "?" matches single character
- "[abc]" matches any char in brackets
- "[!abc]" matches any char NOT in brackets
- "**" recursive directory match
Case-sensitive by default!
Note
Use if_not_pattern for exclusion logic (e.g., skip if output contains ERROR)
if_json_path evaluates JSON output from previous command
# JSON path evaluation (if_json_path):
{
"condition": {
"type": "if_json_path",
"path": "$.status.connected",
"expect": true
}
}
JSON path syntax:
- "$" root object
- ".field" object field access
- "[index]" array index access
- ".." recursive descent
- "*" wildcard (all elements)
Note
Example: health-control --json returns JSON, use if_json_path to check specific fields like $.security.score
if_expression allows complex boolean logic combining multiple checks
# Expression conditions (if_expression):
{
"condition": {
"type": "if_expression",
"expression": "probe('hardened_count') >= 4 && !contains('ERROR', previous_output)"
}
}
Supported operators:
- Comparison: ==, !=, <, >, <=, >=
- Logical: &&, ||, !
- Functions: contains(), count(), probe()
- Variables: previous_output, step_id, workflow_status
Note
Most powerful condition type - use for complex decision logic. Example: skip step if already hardened AND no errors detected
if_probe evaluates reusable probe functions defined in profile
# Probe-based conditions (if_probe):
{
"probes": {
"is_connected": {
"probe_type": "builtin",
"check": "network_status"
}
},
"steps": [
{
"condition": {
"type": "if_probe",
"probe": "is_connected",
"expect": true
}
}
]
}
Note
See Category 11 'Probe Functions' for detailed probe documentation
Step Configuration Reference
Complete reference for all step-level configuration options
All available step configuration fields with example values
# Complete step structure:
{
"id": 1,
"type": "command",
"cmd": "sudo health-control net-check",
"description": "Check network connectivity",
"condition": {
"type": "always"
},
"timeout": 60,
"confirm": false,
"nice_level": 0
}
Note
Required fields: id, type, cmd (if command type), description, condition. All others optional with sensible defaults
Three step types with different requirements and behaviors
# Step types explained:
1. "command" - Execute shell command
Requires: cmd field
Example: "cmd": "sudo tor-switch status"
2. "pause" - Wait for user input or delay
Requires: message field (shown to user)
Example: "message": "Press Enter to continue..."
3. "include" - Include another workflow profile
Requires: profile field
Example: "profile": "base-recovery-sequence"
Note
Include type allows workflow composition - build libraries of reusable profiles and chain them together
Step-level timeout overrides global default_timeout
# Timeout behavior:
{
"global_settings": {
"default_timeout": 300
},
"steps": [
{
"cmd": "quick-command",
"timeout": 10
},
{
"cmd": "slow-command"
# Uses default_timeout (300s)
}
]
}
Note
Set timeout=0 for no limit (use carefully). Commands killed with SIGTERM after timeout, then SIGKILL if unresponsive
confirm adds safety for destructive operations, nice_level controls CPU priority
# Confirm and nice_level:
{
"cmd": "sudo health-control panic hard",
"confirm": true,
"nice_level": -10
}
confirm: true prompts user before executing
nice_level: -20 (highest priority) to 19 (lowest priority)
- Negative values require root (higher CPU priority)
- Positive values lower priority (background tasks)
- 0 is default (normal priority)
Note
Example: Recovery workflows use nice_level=-5 for priority, diagnostic scripts use nice_level=10 for background execution
Environment Variables
| Variable | Description | Default | Values |
|---|---|---|---|
RUST_LOG |
Set logging level | info | error |
NO_COLOR |
Disable all colored output when set | unset | 1 |
Exit Codes
| Code | Description |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Invalid arguments |
| 3 | Permission denied |
| 4 | Network error |
| 5 | File not found |