mirror of
https://github.com/swissmakers/infram.git
synced 2026-05-08 22:49:00 +02:00
55 lines
2.3 KiB
Markdown
55 lines
2.3 KiB
Markdown
# Scripting Variables & Directives
|
|
|
|
Use `@INFRAM:*` directives to make scripts interactive, safer, and easier to operate.
|
|
|
|
## Directive Syntax Reference
|
|
|
|
| Directive | Purpose | Example |
|
|
|---|---|---|
|
|
| `@INFRAM:STEP "text"` | Mark logical execution step | `@INFRAM:STEP "Validate prerequisites"` |
|
|
| `@INFRAM:INPUT <var> "prompt" "default"` | Prompt for free-text input | `@INFRAM:INPUT HOST "Target host" "localhost"` |
|
|
| `@INFRAM:SELECT <var> "prompt" "A" "B"` | Prompt for fixed options | `@INFRAM:SELECT MODE "Deploy mode" "Rolling" "BlueGreen"` |
|
|
| `@INFRAM:CONFIRM "text"` | Require explicit user confirmation | `@INFRAM:CONFIRM "Continue with restart?"` |
|
|
| `@INFRAM:INFO "text"` | Emit informational message | `@INFRAM:INFO "Applying configuration"` |
|
|
| `@INFRAM:WARN "text"` | Emit warning message | `@INFRAM:WARN "Low disk space"` |
|
|
| `@INFRAM:SUCCESS "text"` | Mark successful milestone | `@INFRAM:SUCCESS "Backup completed"` |
|
|
| `@INFRAM:PROGRESS <0-100\|$var>` | Update progress indicator | `@INFRAM:PROGRESS 75` |
|
|
| `@INFRAM:SUMMARY "title" "k1" "v1" ...` | Show structured key/value summary | `@INFRAM:SUMMARY "Result" "Changed" "14"` |
|
|
| `@INFRAM:TABLE "title" "h1" "h2" "r1c1" ...` | Render tabular output | `@INFRAM:TABLE "Users" "Name" "Role" "alice" "admin"` |
|
|
| `@INFRAM:MSGBOX "title" "message"` | Display message dialog | `@INFRAM:MSGBOX "Completed" "Operation finished"` |
|
|
|
|
## End-to-End Example
|
|
|
|
```sh
|
|
@INFRAM:STEP "Collect input"
|
|
@INFRAM:INPUT HOST "Target host" "localhost"
|
|
@INFRAM:SELECT MODE "Deployment mode" "Rolling" "BlueGreen"
|
|
@INFRAM:CONFIRM "Continue with deployment?"
|
|
|
|
@INFRAM:STEP "Deploy"
|
|
@INFRAM:INFO "Starting deployment"
|
|
@INFRAM:PROGRESS 20
|
|
# deployment commands...
|
|
@INFRAM:PROGRESS 100
|
|
@INFRAM:SUCCESS "Deployment finished"
|
|
|
|
@INFRAM:SUMMARY "Deployment Summary" "Host" "$HOST" "Mode" "$MODE" "Status" "Success"
|
|
```
|
|
|
|
## Implementation Notes
|
|
|
|
- Directives are transformed server-side before execution.
|
|
- `sudo` commands are automatically adjusted to support password prompts.
|
|
- Escape literal colons in directive payloads when needed.
|
|
|
|
## Best Practices
|
|
|
|
- Use `STEP` markers in long-running scripts.
|
|
- Use `CONFIRM` before destructive operations.
|
|
- Prefer `SELECT` over free-text where possible.
|
|
- End critical workflows with `SUMMARY` for auditable output.
|
|
|
|
## Related
|
|
|
|
- [Scripts & Snippets](/scripts&snippets)
|