BBR Scenario JSON Documentation

Complete reference for authoring BBR automation scenarios.

Scenario Structure

A scenario is a JSON array of step objects. Each step has an action field and action-specific parameters. 
[
  {"action": "msg", "text": "Hello!", "duration": 2.0},
  {"action": "run_command_silent", "name": "user", "command": "whoami"},
  {"action": "msg", "text": "User: {user_output}", "duration": 3.0}
]

Actions Reference

1. msg — Display Message

Shows a toast notification to the user.

ParameterTypeRequiredDescription
textstring✓Message content (supports {variables})
durationnumber✓Display time in seconds
{
  "action": "msg",
  "text": "Hello, {user_output}! đŸĻĢ",
  "duration": 3.0
}

2. sleep — Pause Execution

Waits for a specified duration before proceeding.

ParameterTypeRequiredDescription
secondsnumber✓Time to wait in seconds
{
  "action": "sleep",
  "seconds": 1.5
}

3. set_context — Set Variable

Stores a value in RunContext for later use.

ParameterTypeRequiredDescription
keystring✓Variable name (alphanumeric, underscores)
valuestring✓Value to store
{
  "action": "set_context",
  "key": "project_name",
  "value": "MyAwesomeProject"
}
Use later: {project_name}

4. run_command_silent — Execute Shell Command

Runs a shell command in the background, capturing output.

ParameterTypeRequiredDescription
namestring✓Identifier for output variable
commandstring✓Shell command to execute
{
  "action": "run_command_silent",
  "name": "current_dir",
  "command": "pwd"
}
Output stored in: {current_dir_output}

5. run_terminal_command — Execute in Visible Terminal

Opens Terminal.app and runs a command visibly.

ParameterTypeRequiredDescription
commandstring✓Command to type and execute
{
  "action": "run_terminal_command",
  "command": "npm run dev"
}

6. extract_regex — Extract Text via Regex

Extracts matching text from a variable using regular expressions.

ParameterTypeRequiredDescription
sourcestring✓Source variable name
patternstring✓Regex pattern (escaped for JSON)
targetstring✓Variable name to store result
modestring—"first" (default) or "all"
groupnumber—Capture group index (default: 0)
{
  "action": "extract_regex",
  "source": "ip_raw_output",
  "pattern": "inet\\s+(\\d+\\.\\d+\\.\\d+\\.\\d+)",
  "target": "local_ip",
  "mode": "first",
  "group": 1
}

7. open_or_focus_app — Activate Application

Opens an application or brings it to foreground.

ParameterTypeRequiredDescription
appstring✓Application name (e.g., "Safari", "Visual Studio Code")
pausenumber—Wait time after opening (seconds)
{
  "action": "open_or_focus_app",
  "app": "Safari",
  "pause": 1.0
}

8. open_url — Navigate to URL

Opens a URL in the default browser.

ParameterTypeRequiredDescription
urlstring✓Full URL (must include https://)
pausenumber—Wait time after loading (seconds)
{
  "action": "open_url",
  "url": "https://github.com",
  "pause": 3.0
}

9. type_text — Human-Like Typing

Types text with realistic keystroke timing.

ParameterTypeRequiredDescription
textstring✓Text to type (supports {variables}, \n for newlines)
intervalnumber—Delay between keystrokes (seconds, default: 0.05)
{
  "action": "type_text",
  "text": "Hello, {user_output}!\n\nThis is typed by Bober.",
  "interval": 0.03
}
Interval guide:
  • 0.02 — Fast (experienced typer)
  • 0.05 — Normal
  • 0.08 — Slow/deliberate

10. hotkey — Keyboard Shortcut

Presses a keyboard shortcut.

ParameterTypeRequiredDescription
modstring✓Modifier key: "command", "option", "control", "shift", or ""
keystring✓Key to press (lowercase letter or special key name)
{
  "action": "hotkey",
  "mod": "command",
  "key": "s"
}
Common shortcuts:
  • Save: {"mod": "command", "key": "s"}
  • New: {"mod": "command", "key": "n"}
  • Close: {"mod": "command", "key": "w"}
  • Enter: {"mod": "", "key": "return"}

11. capture_screen — Screenshot

Captures the current screen and saves to run directory.

ParameterTypeRequiredDescription
(none)——No parameters required
{
  "action": "capture_screen"
}
Image saved to: {runDir}/screenshot-001.png

12. run_subscenario — Execute Another Scenario

Runs another scenario file as part of the current execution.

ParameterTypeRequiredDescription
filestring✓Path to scenario file (relative or absolute)
{
  "action": "run_subscenario",
  "file": "./setup-environment.json"
}

13. run_batch — Iterate with Parameters

Runs a scenario multiple times with different parameter sets.

ParameterTypeRequiredDescription
filestring✓Path to scenario file
prefixstring—Prefix for output variables
paramsarray✓Array of parameter arrays [[p1, p2], [p1, p2], ...]
{
  "action": "run_batch",
  "file": "./run-command.json",
  "prefix": "sys",
  "params": [
    ["hostname", "hostname"],
    ["os_version", "sw_vers -productVersion"],
    ["cpu_arch", "uname -m"]
  ]
}
In the sub-scenario, use {param1}, {param2}. Outputs: {hostname_output}, {os_version_output}, etc.

Conditionals

Add "if" clause to any step to conditionally execute.
OperatorExample
=="if": "status == 'ready'"
!="if": "error != 'none'"
contains"if": "output contains 'success'"
startsWith"if": "path startsWith '/Users'"
endsWith"if": "file endsWith '.json'"
{
  "if": "git_check_output == 'installed'",
  "action": "msg",
  "text": "✓ Git is ready!",
  "duration": 2.5
}

Built-in Variables

VariableDescription
{runDir}Current run's output directory
{name_output}Output from command with name
{param1}, {param2}Batch iteration parameters

Complete Example

[
  {"action": "msg", "text": "đŸĻĢ Starting automation", "duration": 2.0},
  {"action": "set_context", "key": "project", "value": "MyApp"},
  
  {"action": "run_command_silent", "name": "user", "command": "whoami"},
  {"action": "msg", "text": "User: {user_output}", "duration": 3.0},
  
  {"action": "open_or_focus_app", "app": "Safari", "pause": 1.0},
  {"action": "open_url", "url": "https://example.com", "pause": 2.0},
  
  {"action": "capture_screen"},
  {"action": "msg", "text": "✅ Complete!", "duration": 2.0}
]