MacroCLI CLI

What It Is

The MacroCLI converts valuable GUI workflows into parameterized, CLI-callable macros. Agents never touch the GUI directly — they call macros through this stable CLI, and the runtime routes execution to the best available backend (native plugin/API, file transformation, semantic UI control, or precompiled GUI macro replay).

Installation

cd macrocli/agent-harness
pip install -e .

Requirements: Python 3.10+, PyYAML, click, prompt-toolkit.

Quick Start (for agents)

# 1. See what macros are available
cli-anything-macrocli macro list --json

# 2. Inspect a macro's parameters
cli-anything-macrocli macro info export_file --json

# 3. Dry-run to check params without side effects
cli-anything-macrocli --dry-run macro run export_file \
    --param output=/tmp/test.txt --json

# 4. Execute a macro
cli-anything-macrocli macro run export_file \
    --param output=/tmp/result.txt --json

# 5. See what backends are available
cli-anything-macrocli backends --json

Command Reference

Global Flags

Flag	Description
--json	Machine-readable JSON output on stdout
--dry-run	Simulate all steps, skip side effects
--session-id <id>	Resume or create a named session

macro group

Command	Description
macro list	List all available macros
macro info <name>	Show macro schema (parameters, steps, conditions)
macro run <name> --param k=v	Execute a macro
macro dry-run <name> --param k=v	Simulate without side effects
macro validate [name]	Structural validation
macro define <name>	Scaffold a new macro YAML

session group

Command	Description
session status	Show session statistics
session history	Show recent run history
session save	Persist session to disk
session list	List all saved sessions

backends

cli-anything-macrocli backends --json
# Shows: native_api, file_transform, semantic_ui, gui_macro, recovery
# and whether each is available in the current environment.

Macro Parameters

Pass parameters with --param key=value. Repeat for multiple:

cli-anything-macrocli macro run transform_json \
    --param file=/path/to/data.json \
    --param key=settings.theme \
    --param value=dark \
    --json

Output Format (--json)

All commands output JSON when --json is set:

{
  "success": true,
  "macro_name": "export_file",
  "output": {
    "exported_file": "/tmp/result.txt"
  },
  "error": "",
  "telemetry": {
    "duration_ms": 312,
    "steps_total": 2,
    "steps_run": 2,
    "backends_used": ["native_api"],
    "dry_run": false
  }
}

On failure ("success": false), read the "error" field for the reason. Exit code is 1 on failure.

Execution Backends

Backends are selected automatically based on the macro step definition:

Backend	Triggered by	Use case
native_api	backend: native_api	Subprocess / shell command
file_transform	backend: file_transform	XML, JSON, text file editing
semantic_ui	backend: semantic_ui	Accessibility / keyboard shortcuts
gui_macro	backend: gui_macro	Precompiled coordinate replay
recovery	backend: recovery	Retry / fallback orchestration

Writing Macros

Macros are YAML files in cli_anything/macrocli/macro_definitions/. Scaffold one with:

cli-anything-macrocli macro define my_macro --output \
    cli_anything/macrocli/macro_definitions/examples/my_macro.yaml

Minimal schema:

name: my_macro
version: "1.0"
description: What this macro does.

parameters:
  output:
    type: string
    required: true
    description: Where to write results.
    example: /tmp/result.txt

preconditions:
  - file_exists: /path/to/input

steps:
  - id: step1
    backend: native_api
    action: run_command
    params:
      command: [my-app, --export, "${output}"]
    timeout_ms: 30000
    on_failure: fail  # or: skip, continue

postconditions:
  - file_exists: ${output}
  - file_size_gt: [${output}, 100]

outputs:
  - name: result_file
    path: ${output}

agent_hints:
  danger_level: safe  # safe | moderate | dangerous
  side_effects: [creates_file]
  reversible: true

Agent Usage Rules

1. Always use --json for programmatic output.
2. Use --dry-run to validate params before executing side-effectful macros.
3. Check success field — do not assume success from exit code alone.
4. Read error field when success is false — it explains what failed.
5. Use macro info <name> to discover params before calling macro run.
6. Use absolute paths for all file parameters.

Example Workflow

# Step 1: What's available?
cli-anything-macrocli macro list --json

# Step 2: What params does transform_json need?
cli-anything-macrocli macro info transform_json --json

# Step 3: Test safely
cli-anything-macrocli --dry-run macro run transform_json \
    --param file=/tmp/config.json \
    --param key=theme \
    --param value=dark --json

# Step 4: Execute for real
cli-anything-macrocli macro run transform_json \
    --param file=/tmp/config.json \
    --param key=theme \
    --param value=dark --json

Version

1.0.0