run
The run command executes a workflow against target nodes. This is the primary command for running infrastructure automation tasks with actor-IaC.
Synopsis
actor-iac run -w <workflow> [options]
Description
The run command loads a workflow definition from the specified directory (defaults to current directory), optionally applies an overlay for environment-specific customization, and executes the workflow. When an inventory file is provided, the workflow runs against remote nodes via SSH. Without an inventory, the workflow runs locally.
During execution, all actions and their results are logged to an H2 database. The command exits with code 0 on success and non-zero on failure.
Required Options
| Option | Description |
|---|---|
-w, --workflow <name> | Workflow file path relative to the base directory (required). You can specify the name with or without the file extension. |
Base Directory
| Option | Description |
|---|---|
-d, --dir <directory> | Base directory containing workflow files. Defaults to the current directory. Logs are created in this directory. |
Optional Options
Inventory and Targeting
| Option | Description |
|---|---|
-i, --inventory <file> | Path to an Ansible-compatible inventory file. When specified, the workflow executes against remote nodes via SSH. |
-g, --group <name> | Host group to target from the inventory. Defaults to all if not specified. |
--limit <hosts> | Limit execution to specific hosts. Accepts a comma-separated list of hostnames or IP addresses. |
Authentication
| Option | Description |
|---|---|
-k, --ask-pass | Prompt for SSH password before execution. By default, actor-IaC uses SSH agent for key-based authentication. |
Overlay System
| Option | Description |
|---|---|
-o, --overlay <directory> | Overlay directory containing overlay-conf.yaml. Variables, patches, and name transformations from the overlay are applied to the base workflow before execution. |
--render-to <directory> | Render overlay-applied workflows to the specified directory without executing. Useful for previewing the merged workflow. |
Execution
| Option | Description |
|---|---|
-t, --threads <count> | Number of worker threads for CPU-bound operations. Defaults to 4. |
-v, --verbose | Enable verbose output with detailed logging of each step execution. |
Logging
actor-IaC supports three independent log outputs. Each can be enabled/disabled separately:
Console Output (stdout/stderr)
| Option | Description |
|---|---|
-q, --quiet | Suppress all console output (stdout/stderr). Logs are still written to the database. Useful for high-performance batch execution. |
Text File Logging
| Option | Description |
|---|---|
-l, --log, --file-log <file> | Enable text file logging and specify output path. Text logging is disabled by default; only database logging is used unless this option is specified. |
--no-log, --no-file-log | Explicitly disable text file logging. (Since text logging is disabled by default, this option is mainly useful for clarity in scripts.) |
Database Logging (H2)
| Option | Description |
|---|---|
--log-db <path> | H2 database path for structured logging. Defaults to actor-iac-logs in the current directory. |
--no-log-db | Disable H2 database logging. |
--log-serve <host:port> | Connect to an H2 log server at the specified address. Enables multiple workflow processes to share a single log database. Falls back to embedded mode if the server is unreachable. |
--embedded | Use embedded H2 database mode. Default behavior is to auto-start a TCP server with auto-shutdown. |
Display
| Option | Description |
|---|---|
-c, --cowfile <name> | Cowsay character to display at the beginning of each step. Use --cowfile list to show available characters. Defaults to default. See Cowsay Characters for details. |
Other
| Option | Description |
|---|---|
-L, --list-workflows | List discovered workflows and exit without executing. |
Examples
Basic Local Execution
Run a workflow locally without an inventory:
./actor_iac.java run -d ./workflows -w hello-world
Remote Execution with Inventory
Run a workflow against all nodes in the webservers group:
./actor_iac.java run -d ./workflows -w deploy -i inventory.ini -g webservers
Using an Overlay
Apply a production overlay to the base workflow:
./actor_iac.java run -d ./workflows -w deploy -o ./overlays/production -i inventory.ini
Password Authentication
Prompt for SSH password instead of using SSH agent:
./actor_iac.java run -d ./workflows -w deploy -i inventory.ini -g webservers -k
Targeting Specific Hosts
Limit execution to specific hosts:
./actor_iac.java run -d ./workflows -w deploy -i inventory.ini --limit=192.168.1.10,192.168.1.11
Verbose Mode
Enable detailed logging for troubleshooting:
./actor_iac.java run -d ./workflows -w deploy -i inventory.ini -v
Using a Log Server
Connect to a shared log server for centralized logging:
./actor_iac.java run -d ./workflows -w deploy -i inventory.ini --log-serve=localhost:29090
High-Performance Execution
Disable console output for maximum performance (text file logging is disabled by default):
./actor_iac.java run -d ./workflows -w deploy -i inventory.ini --quiet
Minimal Logging
Disable all logging outputs (console, text file, and database):
./actor_iac.java run -d ./workflows -w deploy -i inventory.ini --quiet --no-log-db
Preview Merged Workflow
Render the overlay-applied workflow to see the final result without executing:
./actor_iac.java run -d ./workflows -o ./overlays/production --render-to ./rendered
Custom Cowsay Character
Use a different cowsay character for step display:
./actor_iac.java run -d ./workflows -w deploy -i inventory.ini --cowfile tux
List available cowsay characters:
./actor_iac.java run --cowfile list
Exit Codes
| Code | Description |
|---|---|
| 0 | Workflow completed successfully |
| 1 | Workflow failed or encountered an error |
| 2 | Invalid command-line options |
Logging Behavior
By default, the run command outputs to two destinations:
- Console: Real-time output to stdout/stderr (disable with
-q, --quiet) - H2 database: Structured logs in the current directory (e.g.,
./actor-iac-logs.mv.db). Disable with--no-log-db.
Optionally, you can enable text file logging:
- Text file: Enable with
-l, --log <file>to write logs to a text file. This is disabled by default to avoid creating many log files during batch execution.
The database log enables structured querying with the log-search command. Each execution creates a new session with metadata about the workflow, overlay, inventory, and final status.
Performance Tip
For high-performance batch execution, disable console output which can significantly slow down execution:
./actor_iac.java run -d ./workflows -w deploy -i inventory.ini --quiet
See Also
- list - List available workflows
- describe - Display workflow description
- log-search - Query execution logs
- log-serve - Start a centralized log server
- db-clear - Delete log database files