Platform Support Matrix¶
| Action | Linux | macOS | Windows | FreeBSD | |--------|-------|-------|-------|-------|| | artifact_capture | ✓ | ✓ | ✓ | ✓ | | artifact_validate | ✓ | ✓ | ✓ | ✓ | | assert | ✓ | ✓ | ✓ | ✓ | | command | ✓ | ✓ | ✓ | ✓ | | copy | ✓ | ✓ | ✓ | ✓ | | download | ✓ | ✓ | ✓ | ✓ | | file | ✓ | ✓ | ✓ | ✓ | | file_delete_range | ✓ | ✓ | ✓ | ✓ | | file_insert | ✓ | ✓ | ✓ | ✓ | | file_patch_apply | ✓ | ✓ | ✓ | ✓ | | file_replace | ✓ | ✓ | ✓ | ✓ | | include_vars | ✓ | ✓ | ✓ | ✓ | | package | ✓ | ✓ | ✓ | ✓ | | preset | ✓ | ✓ | ✓ | ✓ | | print | ✓ | ✓ | ✓ | ✓ | | repo_apply_patchset | ✓ | ✓ | ✓ | ✓ | | repo_search | ✓ | ✓ | ✓ | ✓ | | repo_tree | ✓ | ✓ | ✓ | ✓ | | service | ✓ | ✓ | ✓ | ✗ | | shell | ✓ | ✓ | ✓ | ✓ | | template | ✓ | ✓ | ✓ | ✓ | | unarchive | ✓ | ✓ | ✓ | ✓ | | vars | ✓ | ✓ | ✓ | ✓ | | wait | ✓ | ✓ | ✓ | ✓ |
Action Capabilities¶
| Action | Category | Dry-Run | Become | Check Mode |
|---|---|---|---|---|
| artifact_capture | system | Yes | No | No |
| artifact_validate | system | Yes | No | No |
| assert | system | Yes | No | No |
| command | command | Yes | Yes | No |
| copy | file | Yes | Yes | Yes |
| download | network | Yes | Yes | Yes |
| file | file | Yes | Yes | Yes |
| file_delete_range | file | Yes | Yes | Yes |
| file_insert | file | Yes | Yes | Yes |
| file_patch_apply | file | Yes | Yes | Yes |
| file_replace | file | Yes | Yes | Yes |
| include_vars | data | Yes | No | No |
| package | system | Yes | Yes | Yes |
| preset | system | Yes | No | No |
| output | Yes | No | No | |
| repo_apply_patchset | file | Yes | Yes | Yes |
| repo_search | file | Yes | No | No |
| repo_tree | file | Yes | No | No |
| service | system | Yes | No | Yes |
| shell | command | Yes | Yes | No |
| template | file | Yes | Yes | Yes |
| unarchive | file | Yes | No | Yes |
| vars | data | Yes | No | No |
| wait | system | Yes | No | No |
Action Summary¶
Command¶
command¶
Description: Execute commands directly without shell interpolation
Properties:
- Category: command
- Platforms: all
- Supports Dry-Run: Yes
- Supports Become: Yes
- Implements Check: No
- Version: 1.0.0
shell¶
Description: Execute shell commands
Properties:
- Category: command
- Platforms: all
- Supports Dry-Run: Yes
- Supports Become: Yes
- Implements Check: No
- Version: 1.0.0
- Events: step.stdout, step.stderr
File¶
copy¶
Description: Copy files with checksum verification and atomic writes
Properties:
- Category: file
- Platforms: all
- Supports Dry-Run: Yes
- Supports Become: Yes
- Implements Check: Yes
- Version: 1.0.0
- Events: file.copied
file¶
Description: Manage files, directories, links, and permissions
Properties:
- Category: file
- Platforms: all
- Supports Dry-Run: Yes
- Supports Become: Yes
- Implements Check: Yes
- Version: 1.0.0
- Events: file.created, file.updated, file.removed, directory.created, directory.removed, link.created, permissions.changed
file_delete_range¶
Description: Delete text between start and end anchor patterns in files
Properties:
- Category: file
- Platforms: all
- Supports Dry-Run: Yes
- Supports Become: Yes
- Implements Check: Yes
- Version: 1.0.0
- Events: file.updated
file_insert¶
Description: Insert text before or after anchor patterns in files
Properties:
- Category: file
- Platforms: all
- Supports Dry-Run: Yes
- Supports Become: Yes
- Implements Check: Yes
- Version: 1.0.0
- Events: file.updated
file_patch_apply¶
Description: Apply unified diff patches to files
Properties:
- Category: file
- Platforms: all
- Supports Dry-Run: Yes
- Supports Become: Yes
- Implements Check: Yes
- Version: 1.0.0
- Events: file.updated
file_replace¶
Description: Replace text in files using literal or regex patterns
Properties:
- Category: file
- Platforms: all
- Supports Dry-Run: Yes
- Supports Become: Yes
- Implements Check: Yes
- Version: 1.0.0
- Events: file.updated
repo_apply_patchset¶
Description: Apply multiple patches to multiple files atomically
Properties:
- Category: file
- Platforms: all
- Supports Dry-Run: Yes
- Supports Become: Yes
- Implements Check: Yes
- Version: 1.0.0
- Events: file.updated
repo_search¶
Description: Search codebase for patterns and output results in JSON format
Properties:
- Category: file
- Platforms: all
- Supports Dry-Run: Yes
- Supports Become: No
- Implements Check: No
- Version: 1.0.0
repo_tree¶
Description: Generate a JSON representation of directory structure
Properties:
- Category: file
- Platforms: all
- Supports Dry-Run: Yes
- Supports Become: No
- Implements Check: No
- Version: 1.0.0
template¶
Description: Render template files and write to destination
Properties:
- Category: file
- Platforms: all
- Supports Dry-Run: Yes
- Supports Become: Yes
- Implements Check: Yes
- Version: 1.0.0
- Events: template.rendered
unarchive¶
Description: Extract archive files (tar, tar.gz, zip) with path traversal protection
Properties:
- Category: file
- Platforms: all
- Supports Dry-Run: Yes
- Supports Become: No
- Implements Check: Yes
- Version: 1.0.0
- Events: archive.extracted
System¶
artifact_capture¶
Description: Capture file changes with enhanced metadata for LLM agents
Properties:
- Category: system
- Platforms: all
- Supports Dry-Run: Yes
- Supports Become: No
- Implements Check: No
artifact_validate¶
Description: Validate artifacts against constraints (change budgets)
Properties:
- Category: system
- Platforms: all
- Supports Dry-Run: Yes
- Supports Become: No
- Implements Check: No
assert¶
Description: Verify conditions without changing system state
Properties:
- Category: system
- Platforms: all
- Supports Dry-Run: Yes
- Supports Become: No
- Implements Check: No
package¶
Description: Manage system packages (install/remove/update)
Properties:
- Category: system
- Platforms: linux, darwin, windows, freebsd
- Supports Dry-Run: Yes
- Supports Become: Yes
- Implements Check: Yes
- Version: 1.0.0
- Events: package.managed
preset¶
Description: Execute a preset by expanding it into steps
Properties:
- Category: system
- Platforms: all
- Supports Dry-Run: Yes
- Supports Become: No
- Implements Check: No
service¶
Description: Manage services across platforms (systemd, launchd, Windows)
Properties:
- Category: system
- Platforms: linux, darwin, windows
- Supports Dry-Run: Yes
- Supports Become: No
- Implements Check: Yes
wait¶
Description: Poll a condition until it becomes true or times out
Properties:
- Category: system
- Platforms: all
- Supports Dry-Run: Yes
- Supports Become: No
- Implements Check: No
Data¶
include_vars¶
Description: Load variables from YAML files
Properties:
- Category: data
- Platforms: all
- Supports Dry-Run: Yes
- Supports Become: No
- Implements Check: No
- Version: 1.0.0
- Events: variables.loaded
vars¶
Description: Set variables for use in subsequent steps
Properties:
- Category: data
- Platforms: all
- Supports Dry-Run: Yes
- Supports Become: No
- Implements Check: No
- Version: 1.0.0
- Events: variables.set
Network¶
download¶
Description: Download files from URLs with checksum verification
Properties:
- Category: network
- Platforms: all
- Supports Dry-Run: Yes
- Supports Become: Yes
- Implements Check: Yes
- Version: 1.0.0
- Events: file.downloaded
Output¶
print¶
Description: Display messages to the user
Properties:
- Category: output
- Platforms: all
- Supports Dry-Run: Yes
- Supports Become: No
- Implements Check: No
- Version: 1.0.0
- Events: print.message
Schema Documentation¶
YAML Schema Documentation¶
The following schemas are generated from Go struct definitions. All field names and types are guaranteed to match the implementation.
PresetDefinition¶
Defines a reusable preset with parameters and steps.
Fields:
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Unique preset identifier |
description |
string | Yes | Human-readable description of what the preset does |
version |
string | Yes | Semantic version (e.g., 1.0.0) |
parameters |
map[string]PresetParameter | Yes | Map of parameter definitions |
steps |
[]Step | No | Array of steps to execute |
Example YAML:
name: my-preset
description: Description of what this preset does
version: 1.0.0
parameters:
param_name:
type: string
required: true
description: Parameter description
steps:
- name: Example step
shell: echo "hello"
PresetParameter¶
Defines a parameter that can be passed to a preset.
Fields:
| Field | Type | Required | Description |
|---|---|---|---|
type |
string | Yes | Parameter type (string, bool, array, object) |
required |
bool | Yes | Whether the parameter must be provided |
default |
interface{} | Yes | Default value if not provided |
enum |
[]interface{} | Yes | List of valid values (if restricted) |
description |
string | Yes | Human-readable parameter description |
Example YAML:
PresetInvocation¶
Invokes a preset in a playbook (user-facing syntax).
Fields:
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Name of the preset to invoke |
with |
map[string]interface{} | Yes | Map of parameter values to pass to preset |
Example YAML: