Binary reference

workflow-manager

Workflow manager for batch command execution with conditional logic

Version9.8.4 (build 320)Size4.2MBAuthorWarith Al MaawaliLicenseProprietaryWebsitehttps://www.digi77.com

File Information

Property	Value
Binary Name	workflow-manager
Version	9.8.4 (build 320)
Build Date	Not disclosed
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-07-11T18:16:21Z
Binary Timestamp	Unknown
JSON Data	View Raw JSON

SHA256 Checksum

6557b8b5945232bd9d28e6f5b4c155bb718313298a4a8f141c142fe587142e1d

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)
`--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\|warn\|info\|debug)
`--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

`create`

Create a new workflow template

Usage:

workflow-manager create [OPTIONS]

`add`

Add a step to a workflow template

Usage:

workflow-manager add [OPTIONS]

`pause`

Add a pause step to a workflow template

Usage:

workflow-manager pause [OPTIONS]

`include`

Add an include step to a workflow template (includes another profile)

Usage:

workflow-manager include [OPTIONS]

`list`

List all workflow templates

Usage:

workflow-manager list [OPTIONS]

`show`

Show details of a workflow template

Usage:

workflow-manager show [OPTIONS]

`run`

Run a workflow template

Usage:

workflow-manager run [OPTIONS]

`update`

Update a step in a workflow template

Usage:

workflow-manager update [OPTIONS]

`delete-step`

Delete a step from a workflow template

Usage:

workflow-manager delete-step [OPTIONS]

`delete`

Delete an entire workflow template

Usage:

workflow-manager delete [OPTIONS]

`state`

Query system state

Usage:

workflow-manager state [OPTIONS]

`prereq`

Validate workflow prerequisites

Usage:

workflow-manager prereq [OPTIONS]

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'

workflow-manager create my-workflow

Expected Output: Template 'my-workflow' created successfully

Step 2: Creates a workflow with a descriptive label

workflow-manager create backup-workflow --description 'Daily backup routine'

Expected Output: Template 'backup-workflow' created successfully

Step 3: Shows all available workflow templates

workflow-manager list

Expected Output: Workflow Templates (2 total)

Step 4: Displays the full structure of a workflow template

workflow-manager show my-workflow

Expected Output: Workflow Template: my-workflow

Step 5: Permanently removes a workflow template

workflow-manager delete my-workflow

Expected Output: Template 'my-workflow' deleted successfully

Scenario 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

workflow-manager add my-workflow 'echo Hello World'

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"

Expected Output: Template 'w1' created, 3 steps added to template 'w1'

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"

Expected Output: Template 'diagnostics' created, 3 steps added

Note

All steps share the same timeout and condition settings

Step 4: Adds a command with a 10-minute timeout

workflow-manager add my-workflow 'tar czf backup.tar.gz /data' --timeout 600

Expected Output: Step added with 600 second timeout

Step 5: Runs only if the previous command succeeded

workflow-manager add my-workflow 'cleanup.sh' --condition if_success

Expected Output: Step added with conditional execution

Step 6: Runs only if previous output contains 'ERROR'

workflow-manager add my-workflow 'notify-admin.sh' --if-contains 'ERROR'

Expected Output: Step added with pattern matching condition

Scenario 3: Workflow Execution

Run workflows and control execution behavior

Step 1: Executes all commands in the workflow sequentially

sudo workflow-manager run my-workflow

Expected Output: ✅ Workflow completed: Success

Note

Conditions are evaluated before each step

Step 2: Shows what would be executed without running commands

sudo workflow-manager run my-workflow --dry-run

Expected Output: Dry run: 5 steps would be executed

Note

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

workflow-manager show my-workflow

Expected Output: Step 1: echo Hello Step 2: ./backup.sh Step 3: ./cleanup.sh

Note

Use this to identify step IDs before updating or deleting

Step 2: Remove step #2 from the workflow

workflow-manager delete-step my-workflow 2

Expected Output: Step 2 deleted from 'my-workflow'

Note

Step IDs are renumbered after deletion

Step 3: Change step #1 command and timeout

workflow-manager update my-workflow 1 'echo Updated Command' --timeout 300

Expected Output: Step 1 updated successfully

Note

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

Expected Output: Template created, 3 steps added successfully

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

Expected Output: diagnostics created, 4 steps added

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

Expected Output: Backup workflow with 4 steps created

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)

workflow-manager add my-workflow './check-status.sh' -c always

Expected Output: Step added with 'always' condition

Step 2: Execute only if previous step succeeded (exit code 0)

workflow-manager add my-workflow './deploy.sh' -c if_success

Expected Output: Step added with if_success condition

Note

Most common condition for sequential workflows

Step 3: Execute only if previous step failed (exit code ≠ 0)

workflow-manager add my-workflow './rollback.sh' -c if_fail

Expected Output: Step added with if_fail condition

Note

Useful for error recovery and rollback scenarios

Step 4: Execute if previous output contains pattern "success"

workflow-manager add my-workflow './alert-success.sh' --if-contains "success"

Expected Output: Step added with pattern matching condition

Note

Case-sensitive - matches JSON like \"status\":\"success\"

Step 5: Execute if previous output does NOT contain "errors"

workflow-manager add my-workflow './continue.sh' --if-not-contains "errors"

Expected Output: Step added with negative pattern condition

Note

Case-sensitive - checks for absence of \"errors\" in JSON output

Step 6: Execute if previous output exactly equals "ready"

workflow-manager add my-workflow './handle-done.sh' --if-equals "ready"

Expected Output: Step added with exact match condition

Note

Exact match (case-sensitive) - output is trimmed before comparison

Step 7: Execute if previous output matches regex pattern

workflow-manager add my-workflow './process-result.sh' --if-regex '^status: (ok|success)$'

Expected Output: Step added with regex condition

Note

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'

Expected Output: Step added with if_not_regex condition

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)

workflow-manager add my-workflow './alert-few-services.sh' --if-not-regex '(service.*active.*){5,}'

Expected Output: Step added with if_not_regex condition

Note

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'

workflow-manager add my-workflow './handle-connected.sh' --if-json-path '$.status="connected"'

Expected Output: Step added with JSON path condition

Note

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"'

Expected Output: Step added with JSON path array condition

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"'

Expected Output: Step added with complex nested JSON path condition

Note

Can navigate through objects and arrays: $.path.to.array[index].field

Step 13: Execute if JSON boolean field is true

workflow-manager add my-workflow './ip-online.sh' --if-json-path '$.ip_connectivity=true'

Expected Output: Step added with JSON boolean condition

Note

Supports true/false without quotes

Step 14: Execute if JSON number field matches

workflow-manager add my-workflow './status-check.sh' --if-json-path '$.status_code=2'

Expected Output: Step added with JSON number condition

Note

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

workflow-manager pause my-workflow --message 'Review results before continuing'

Expected Output: Pause step added to workflow

Note

User must press Enter to continue workflow execution

Step 2: Conditional pause only if previous step succeeded

workflow-manager pause backup --message 'Verify backup integrity' -c if_success

Expected Output: Conditional pause step added

Note

Combine pauses with conditions for smart workflows

Step 3: Adds an include step that composes another workflow profile into this template

workflow-manager include my-workflow shared-prereqs --description 'Reusable setup steps'

Expected Output: Include step 3 added to template 'my-workflow'

Note

The profile is expanded into its steps when the workflow runs. Requires <TEMPLATE> and <PROFILE> positionals; accepts -c/--condition like other steps.

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

Expected Output: Finland detected

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

Expected Output: Session valid

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

Expected Output: Network online

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

Expected Output: Tor responding

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"
  }
}

Expected Output: ✅ Prerequisites validated or ❌ Prerequisites not met - aborting

Note

If prerequisites is null or not present, no prerequisite checks are performed

Step 2: Validate prerequisites without running the workflow

workflow-manager prereq check initial_terminal_setup_wireguard_torrify

Expected Output: ✅ All prerequisites met or ❌ Prerequisite failures listed

Note

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

workflow-manager state

Expected Output: {"online": true, "torrify": false, "dnscrypt": true, "routing_mode": "wireguard", "tor_running": true}

Step 2: Check specific state (online connectivity)

workflow-manager state online

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
      }
    }
  ]
}

Expected Output: Step executes based on probe evaluation

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": "."
  }
}

Expected Output: kill_policy: "stop" (how to handle step failures) continue_policy: true (whether to continue after failures) max_log_size: 10485760 bytes (max log file size) default_timeout: 300 seconds (default step timeout) working_dir: "." (base directory for commands)

Note

Global settings apply to entire workflow unless overridden at step level

Step 2: kill_policy determines workflow behavior when steps fail

workflow-manager show policy-demo --json

Expected Output: Profile JSON showing global_settings.kill_policy and continue_policy values

Note

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

Expected Output: continue_policy acts as master override switch kill_policy provides granular control when continue_policy=false

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
    }
  ]
}

Expected Output: Steps without explicit timeout use default_timeout (180s) Commands execute from working_dir path Step-level timeout (60s) overrides default

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"
  }
}

Expected Output: authenticated: User must be logged in with valid session online: Internet connectivity required torrify: Tor routing must be active (true) or inactive (false) on_failure: Action when prerequisites not met

Note

Prerequisites are checked BEFORE any steps execute. All must pass (AND logic)

Step 2: on_failure controls behavior when prerequisites fail

workflow-manager show prereq-demo --json

Expected Output: Profile JSON showing prerequisites.on_failure policy

Note

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

Expected Output: Security workflows: Require authentication Setup workflows: Require specific system state Recovery workflows: No prerequisites (always available)

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

Expected Output: Each prerequisite type has specific system check Failed checks trigger on_failure behavior Prerequisite status shown in workflow output

Note

Use 'workflow-manager prereq check <profile>' to test prerequisites without running workflow

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

Expected Output: Each condition type evaluates differently Conditions determine whether step executes or skips Multiple steps can have same condition type

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!

Expected Output: Patterns match against previous step's output Wildcards allow partial matching Case matters: 'SUCCESS' != 'success'

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)

Expected Output: Extracts value at path and compares to 'expect' Useful for structured command output (health-control, tor-switch) Path evaluation uses a strict JSONPath subset (dot fields + array indexes)

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"

Expected Output: Step added with if_expression condition for runtime evaluation

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
      }
    }
  ]
}

Expected Output: Define probe once, use in multiple steps Probe types: builtin (system checks), expression (custom logic), count (occurrence counting) Cleaner than repeating same condition

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
}

Expected Output: id: Unique step number (required, integer) type: Step type (required: 'command', 'pause', 'include') cmd: Command to execute (required for command type) description: Human-readable label (required) condition: Execution condition (required object) timeout: Max execution seconds (optional, uses default_timeout if omitted) confirm: Require user confirmation (optional, default false) nice_level: Process priority -20 to 19 (optional, default 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"

Expected Output: command: Most common type for executing system operations pause: Interactive workflows requiring user decisions include: Compose complex workflows from smaller reusable pieces

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)
    }
  ]
}

Expected Output: Omit timeout to use default (300s from global_settings) Specify timeout for time-sensitive commands Timeout prevents hanging on stuck commands

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)

Expected Output: Use confirm=true for dangerous commands (panic, wipe, reset) Use negative nice_level for critical real-time operations Use positive nice_level for background tasks

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\|warn\|info\|debug\|trace
`NO_COLOR`	Disable all colored output when set	unset	1\|true\|yes (any value disables color)

Exit Codes

Code	Description
0	Success
1	General error
2	Invalid arguments
3	Permission denied
4	Network error
5	File not found