workflow-manager
Workflow manager for batch command execution with conditional logic
Version: 9.0.1 | Size: 4.2MB | 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 | REDACTED-BUILD-TIME |
| Rust Version | 1.82.0 |
| File Size | 4.2MB |
| Author | Warith Al Maawali |
| License | Proprietary |
| Category | Kodachi Binary |
| Description | Workflow manager for batch command execution with conditional logic |
| Git Commit | unknown |
| Metadata Generated | 2026-06-23T12:05:02Z |
| Binary Timestamp | Unknown |
| JSON Data | View Raw JSON |
SHA256 Checksum
Features
| # | Feature |
|---|---|
| 1 | Template-based workflow management |
| 2 | Conditional command execution |
| 3 | Batch processing with retry logic |
| 4 | State tracking and logging |
| 5 | Concurrent execution support |
| 6 | Pause steps with user confirmation |
| 7 | Pattern matching and regex conditions |
| 8 | JSON path subset support (dot fields + array indexes) |
| 9 | Prerequisites validation before execution |
| 10 | System state checking and probes |
| 11 | Reusable probe functions for conditions |
Security Features
| Feature | Description |
|---|---|
| Authentication | Not provided by cli-core (see online-auth) |
| Encryption | Not provided by cli-core |
| Input Validation | Argument parsing via clap; per-command validation is the consumer's responsibility |
| Rate Limiting | Not provided by cli-core |
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 |
-o, --output-format <FORMAT> |
Force output format (text |
--json-pretty |
Pretty-print JSON output with indentation |
--json-human |
Enhanced JSON output with improved formatting (like jq) |
--fields <FIELD_LIST> |
Select specific fields to include in output (comma-separated) |
--limit <NUMBER> |
Limit number of results returned |
--offset <NUMBER> |
Skip first N results (for pagination) |
-d, --work-dir <PATH> |
Working directory (defaults to auto-detected base directory) |
--port <PORT> |
Set custom port number (1024-65535) |
--log-level <LEVEL> |
Set log level (error |
--verbose |
Enable verbose output |
--quiet |
Suppress non-essential output |
--no-color |
Disable colored output |
--config <FILE> |
Use custom configuration file |
--timeout <SECS> |
Set operation timeout in seconds (optional; no default applied) |
--retry <COUNT> |
Retry attempts (optional; no default applied) |
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:
include
Add an include step to a workflow template (includes another profile)
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:
Operational Scenarios
Scenario-oriented workflows generated from the binary's built-in -e --json examples.
Scenario 1: Template Management
Create, list, view, and delete workflow templates
Step 1: Creates a new empty workflow template named 'my-workflow'
Expected Output: Template 'my-workflow' created successfullyStep 2: Creates a workflow with a descriptive label
Expected Output: Template 'backup-workflow' created successfullyStep 3: Shows all available workflow templates
Expected Output: Workflow Templates (2 total)Step 4: Displays the full structure of a workflow template
Expected Output: Workflow Template: my-workflowStep 5: Permanently removes a workflow template
Expected Output: Template 'my-workflow' deleted successfullyScenario 2: Adding Commands to Workflows
Add steps to workflows. Use comma-separated commands for multiple steps in one call, or add individually.
Step 1: Adds a single command as step 1
Expected Output: Step 1 added to template 'my-workflow'Note
Single command creates one step
Step 2: Create workflow then add multiple steps in one command using comma separation
workflow-manager create w1 && workflow-manager add w1 "sudo ip-fetch","sudo online-auth check-login","ip addr show"
Note
add requires the workflow to already exist, so chain create first. Comma-separated commands create multiple steps automatically.
Step 3: Create a diagnostic workflow with 3 steps at once
workflow-manager create diagnostics && workflow-manager add diagnostics "./health-control net-check","./tor-switch tor-status","./dns-leak test"
Note
All steps share the same timeout and condition settings
Step 4: Adds a command with a 10-minute timeout
Expected Output: Step added with 600 second timeoutStep 5: Runs only if the previous command succeeded
Expected Output: Step added with conditional executionStep 6: Runs only if previous output contains 'ERROR'
Expected Output: Step added with pattern matching conditionScenario 3: Workflow Execution
Run workflows and control execution behavior
Step 1: Executes all commands in the workflow sequentially
Expected Output: ✅ Workflow completed: SuccessNote
Conditions are evaluated before each step
Step 2: Shows what would be executed without running commands
Expected Output: Dry run: 5 steps would be executedNote
Use for testing workflows before execution
Scenario 4: Managing Individual Steps
Update, delete, and inspect individual workflow steps
Step 1: 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
Step 2: Remove step #2 from the workflow
Expected Output: Step 2 deleted from 'my-workflow'Note
Step IDs are renumbered after deletion
Step 3: Change step #1 command and timeout
Expected Output: Step 1 updated successfullyNote
All step properties can be updated
Scenario 5: Efficient Batch Building
Build complete workflows quickly by chaining multiple 'add' commands with &&
Step 1: 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
Step 2: Create and populate a diagnostics workflow with 4 conditional steps
workflow-manager create 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
Note
Chain create before add so the workflow exists before steps are appended.
Step 3: Build complete backup workflow with pause and cleanup
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
Note
Mix commands and pauses for interactive workflows. create precedes all add/pause calls.
Scenario 6: Conditional Logic
All available condition types with practical examples
Step 1: Always execute (default behavior, runs regardless)
Expected Output: Step added with 'always' conditionStep 2: Execute only if previous step succeeded (exit code 0)
Expected Output: Step added with if_success conditionNote
Most common condition for sequential workflows
Step 3: Execute only if previous step failed (exit code ≠ 0)
Expected Output: Step added with if_fail conditionNote
Useful for error recovery and rollback scenarios
Step 4: Execute if previous output contains pattern "success"
Expected Output: Step added with pattern matching conditionNote
Case-sensitive - matches JSON like \"status\":\"success\"
Step 5: 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
Step 6: Execute if previous output exactly equals "ready"
Expected Output: Step added with exact match conditionNote
Exact match (case-sensitive) - output is trimmed before comparison
Step 7: Execute if previous output matches regex pattern
Expected Output: Step added with regex conditionNote
Supports full regex syntax for complex matching
Step 8: 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.
Step 9: 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).
Step 10: Execute if JSON field $.status equals 'connected'
Expected Output: Step added with JSON path conditionNote
Previous output must be valid JSON
Step 11: 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
Step 12: 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
Step 13: Execute if JSON boolean field is true
Expected Output: Step added with JSON boolean conditionNote
Supports true/false without quotes
Step 14: Execute if JSON number field matches
Expected Output: Step added with JSON number conditionNote
Numbers don't need quotes: =2 not ="2"
Scenario 7: Advanced Features
Pause steps and advanced workflow management
Step 1: Adds an interactive pause point in the workflow
Expected Output: Pause step added to workflowNote
User must press Enter to continue workflow execution
Step 2: Conditional pause only if previous step succeeded
Expected Output: Conditional pause step addedNote
Combine pauses with conditions for smart workflows
Step 3: Adds an include step that composes another workflow profile into this template
Expected Output: Include step 3 added to template 'my-workflow'Note
The profile is expanded into its steps when the workflow runs. Requires and
Scenario 8: Real-World Kodachi Workflows
Practical workflows using actual Kodachi commands
Step 1: 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
Step 2: 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
Step 3: 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
Step 4: 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
Scenario 9: Prerequisites
Define system state requirements that must be met before workflow execution
Step 1: 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
Step 2: Validate prerequisites without running the workflow
Expected Output: ✅ All prerequisites met or ❌ Prerequisite failures listedNote
Use this to test prerequisites before execution
Scenario 10: System State Checking
Query current system state for debugging and validation
Step 1: Show all system states as JSON
Expected Output: {"online": true, "torrify": false, "dnscrypt": true, "routing_mode": "wireguard", "tor_running": true}Step 2: 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
Scenario 11: Probe Functions
Define reusable probe functions in profiles for complex conditions
Step 1: 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
Scenario 12: Global Settings Reference
Complete reference for workflow-level configuration options and their interactions
Step 1: 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
Step 2: kill_policy determines workflow behavior when steps fail
Expected Output: Profile JSON showing global_settings.kill_policy and continue_policy valuesNote
kill_policy options: stop (default/safest), continue (best-effort), skip_remaining (skip rest without fail). continue_policy=true overrides kill_policy and always continues.
Step 3: 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
Step 4: 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": "."
},
"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
Scenario 13: Prerequisites Explained
Complete guide to workflow prerequisites - requirements that must be met before workflow runs
Step 1: 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)
Step 2: on_failure controls behavior when prerequisites fail
Expected Output: Profile JSON showing prerequisites.on_failure policyNote
on_failure options: abort (default/safest), skip (optional workflows), warn (informational checks). Use abort for auth/security-critical flows.
Step 3: 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
Step 4: 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
Scenario 14: Condition Types Deep Dive
Comprehensive reference for all condition types and evaluation logic
Step 1: 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 (dot fields + [index]) 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
Step 2: 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)
Step 3: 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
Unsupported in this matcher:
- ".." recursive descent
- "*" wildcard (all elements)
Note
Example: health-control --json returns JSON, use if_json_path to check specific fields like $.security.score
Step 4: if_expression allows complex boolean logic combining multiple checks
workflow-manager add my-workflow './health-control security-status --json' --if-expression "probe('hardened_count') >= 4"
Note
Supported operators: comparison (== != < > <= >=), logical (&& || !), functions (contains(), count(), probe()), and variables (previous_output, step_id, workflow_status).
Step 5: 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
Scenario 15: Step Configuration Reference
Complete reference for all step-level configuration options
Step 1: 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
Step 2: Three step types with different requirements and behaviors
# Step types explained:
1. "command" - Execute shell command
Requires: cmd field
Example: "cmd": "sudo tor-switch tor-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 3: 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
Step 4: 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 |