MacroCLI CLI

Was macht MacroCLI CLI?

Was es ist

Das MacroCLI konvertiert wertvolle GUI-Workflows in parametrisierbare, CLI-aufrufbare Makros. Agenten berühren die GUI nie direkt – sie rufen Makros über dieses stabile CLI auf, und die Laufzeitumgebung leitet die Ausführung an das beste verfügbare Backend weiter (natives Plugin/API, Dateitransformation, semantische UI-Steuerung oder vorkompilierte GUI-Makro-Wiedergabe).

Installation

cd macrocli/agent-harness
pip install -e .

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

Kurzstart (für Agenten)

# 1. Anzeigen, welche Makros verfügbar sind
cli-anything-macrocli macro list --json

# 2. Parameter eines Makros anzeigen
cli-anything-macrocli macro info export_file --json

# 3. Trockentest, um Parameter ohne Nebenwirkungen zu prüfen
cli-anything-macrocli --dry-run macro run export_file \
    --param output=/tmp/test.txt --json

# 4. Ein Makro ausführen
cli-anything-macrocli macro run export_file \
    --param output=/tmp/result.txt --json

# 5. Anzeigen, welche Backends verfügbar sind
cli-anything-macrocli backends --json

Befehlsreferenz

Globale Flags

Flag	Beschreibung
--json	Maschinenlesbare JSON-Ausgabe auf stdout
--dry-run	Alle Schritte simulieren, Nebenwirkungen überspringen
--session-id <id>	Eine benannte Sitzung fortsetzen oder erstellen

macro-Gruppe

Befehl	Beschreibung
macro list	Alle verfügbaren Makros auflisten
macro info <name>	Makro-Schema anzeigen (Parameter, Schritte, Bedingungen)
macro run <name> --param k=v	Ein Makro ausführen
macro dry-run <name> --param k=v	Ohne Nebenwirkungen simulieren
macro validate [name]	Strukturelle Validierung
macro define <name>	Ein neues Makro-YAML-Gerüst erstellen

session-Gruppe

Befehl	Beschreibung
session status	Sitzungsstatistiken anzeigen
session history	Kürzliche Ausführungshistorie anzeigen
session save	Sitzung auf Festplatte speichern
session list	Alle gespeicherten Sitzungen auflisten

backends

cli-anything-macrocli backends --json
# Zeigt: native_api, file_transform, semantic_ui, gui_macro, recovery
# und ob jedes in der aktuellen Umgebung verfügbar ist.

Makro-Parameter

Parameter mit --param key=value übergeben. Für mehrere wiederholen:

cli-anything-macrocli macro run transform_json \
    --param file=/pfad/zu/daten.json \
    --param key=settings.theme \
    --param value=dark \
    --json

Ausgabeformat (--json)

Alle Befehle geben JSON aus, wenn --json gesetzt ist:

{
  "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
  }
}

Bei Fehlschlag ("success": false) das "error"-Feld lesen, um den Grund zu erfahren. Der Exit-Code ist bei Fehlschlag 1.

Ausführungs-Backends

Backends werden automatisch basierend auf der Makro-Schritt-Definition ausgewählt:

Backend	Ausgelöst durch	Anwendungsfall
native_api	backend: native_api	Subprozess / Shell-Befehl
file_transform	backend: file_transform	XML-, JSON-, Textdatei-Bearbeitung
semantic_ui	backend: semantic_ui	Barrierefreiheit / Tastaturkürzel
gui_macro	backend: gui_macro	Vorkompilierte Koordinatenwiedergabe
recovery	backend: recovery	Wiederholungs- / Fallback-Orchestrierung

Makros schreiben

Makros sind YAML-Dateien in cli_anything/macrocli/macro_definitions/. Ein Gerüst erstellen mit:

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

Minimales Schema:

name: my_macro
version: "1.0"
beschreibung: Was dieses Makro tut.

parameters:
  output:
    type: string
    required: true
    beschreibung: Wohin die Ergebnisse geschrieben werden.
    beispiel: /tmp/result.txt

preconditions:
  - file_exists: /pfad/zu/eingabe

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

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

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

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

Agenten-Nutzungsregeln

1. Immer --json verwenden für programmatische Ausgabe.
2. --dry-run verwenden, um Parameter zu validieren, bevor Makros mit Nebenwirkungen ausgeführt werden.
3. success-Feld prüfen – nicht allein aus dem Exit-Code auf Erfolg schließen.
4. error-Feld lesen, wenn success false ist – es erklärt den Fehler.
5. macro info <name> verwenden, um Parameter zu entdecken, bevor macro run aufgerufen wird.
6. Absolute Pfade für alle Dateiparameter verwenden.

Beispiel-Workflow

# Schritt 1: Was ist verfügbar?
cli-anything-macrocli macro list --json

# Schritt 2: Welche Parameter benötigt transform_json?
cli-anything-macrocli macro info transform_json --json

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

# Schritt 4: Wirklich ausführen
cli-anything-macrocli macro run transform_json \
    --param file=/tmp/config.json \
    --param key=theme \
    --param value=dark --json

Version

1.0.0