MacroCLI CLI

¿Qué hace MacroCLI CLI?

Qué Es

MacroCLI convierte flujos de trabajo GUI valiosos en macros parametrizadas y invocables desde la CLI. Los agentes nunca tocan la GUI directamente — llaman a macros a través de esta CLI estable, y el runtime enruta la ejecución al mejor backend disponible (plugin/API nativa, transformación de archivos, control semántico de UI, o reproducción de macro GUI precompilada).

Instalación

cd macrocli/agent-harness
pip install -e .

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

Inicio Rápido (para agentes)

# 1. Ver qué macros están disponibles
cli-anything-macrocli macro list --json

# 2. Inspeccionar los parámetros de una macro
cli-anything-macrocli macro info export_file --json

# 3. Ejecución en seco para verificar parámetros sin efectos secundarios
cli-anything-macrocli --dry-run macro run export_file \
    --param output=/tmp/test.txt --json

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

# 5. Ver qué backends están disponibles
cli-anything-macrocli backends --json

Referencia de Comandos

Banderas Globales

Bandera	Descripción
--json	Salida JSON legible por máquina en stdout
--dry-run	Simular todos los pasos, omitir efectos secundarios
--session-id <id>	Reanudar o crear una sesión con nombre

Grupo macro

Comando	Descripción
macro list	Listar todas las macros disponibles
macro info <name>	Mostrar esquema de la macro (parámetros, pasos, condiciones)
macro run <name> --param k=v	Ejecutar una macro
macro dry-run <name> --param k=v	Simular sin efectos secundarios
macro validate [name]	Validación estructural
macro define <name>	Crear esqueleto de una nueva macro YAML

Grupo session

Comando	Descripción
session status	Mostrar estadísticas de la sesión
session history	Mostrar historial de ejecuciones recientes
session save	Persistir sesión en disco
session list	Listar todas las sesiones guardadas

backends

cli-anything-macrocli backends --json
# Muestra: native_api, file_transform, semantic_ui, gui_macro, recovery
# e indica si cada uno está disponible en el entorno actual.

Parámetros de Macros

Pasa parámetros con --param clave=valor. Repite para múltiples:

cli-anything-macrocli macro run transform_json \
    --param file=/ruta/a/datos.json \
    --param key=settings.theme \
    --param value=dark \
    --json

Formato de Salida (--json)

Todos los comandos emiten JSON cuando se establece --json:

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

En caso de fallo ("success": false), lee el campo "error" para conocer el motivo. El código de salida es 1 en caso de fallo.

Backends de Ejecución

Los backends se seleccionan automáticamente según la definición del paso de la macro:

Backend	Activado por	Caso de uso
native_api	backend: native_api	Subproceso / comando shell
file_transform	backend: file_transform	Edición de archivos XML, JSON, texto
semantic_ui	backend: semantic_ui	Accesibilidad / atajos de teclado
gui_macro	backend: gui_macro	Reproducción de coordenadas precompiladas
recovery	backend: recovery	Orquestación de reintentos / fallback

Escribir Macros

Las macros son archivos YAML en cli_anything/macrocli/macro_definitions/. Crea un esqueleto con:

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

Esquema mínimo:

name: my_macro
version: "1.0"
description: Qué hace esta macro.

parameters:
  output:
    type: string
    required: true
    description: Dónde escribir los resultados.
    example: /tmp/resultado.txt

preconditions:
  - file_exists: /ruta/a/entrada

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

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

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

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

Reglas de Uso para Agentes

1. Siempre usa --json para salida programática.
2. Usa --dry-run para validar parámetros antes de ejecutar macros con efectos secundarios.
3. Verifica el campo success — no asumas éxito solo por el código de salida.
4. Lee el campo error cuando success sea falso — explica qué falló.
5. Usa macro info <nombre> para descubrir parámetros antes de llamar a macro run.
6. Usa rutas absolutas para todos los parámetros de archivo.

Ejemplo de Flujo de Trabajo

# Paso 1: ¿Qué hay disponible?
cli-anything-macrocli macro list --json

# Paso 2: ¿Qué parámetros necesita transform_json?
cli-anything-macrocli macro info transform_json --json

# Paso 3: Probar de forma segura
cli-anything-macrocli --dry-run macro run transform_json \
    --param file=/tmp/config.json \
    --param key=theme \
    --param value=dark --json

# Paso 4: Ejecutar realmente
cli-anything-macrocli macro run transform_json \
    --param file=/tmp/config.json \
    --param key=theme \
    --param value=dark --json

Versión

1.0.0