cli-anything-macrocli

# 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 ```bash cd macrocli/agent-harness pip install -e . ``` **Requirements:** Python 3.10+, PyYAML, click, prompt-toolkit. ## Quick Start (for agents) ```bash # 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` ```bash 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: ```bash 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: ```json { "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: ```bash cli-anything-macrocli macro define my_macro --output \ cli_anything/macrocli/macro_definitions/examples/my_macro.yaml ``` Minimal schema: ```yaml 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 ```bash # 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