MacroCLI CLI

Que fait MacroCLI CLI ?

Ce que c'est

MacroCLI convertit des flux de travail GUI utiles en macros paramétrables et appelables via CLI. Les agents ne touchent jamais la GUI directement — ils appellent des macros via cette CLI stable, et le runtime achemine l'exécution vers le meilleur backend disponible (plugin natif/API, transformation de fichier, contrôle sémantique de l'interface utilisateur ou relecture de macro GUI précompilée).

Installation

cd macrocli/agent-harness
pip install -e .

Prérequis : Python 3.10+, PyYAML, click, prompt-toolkit.

Démarrage rapide (pour les agents)

# 1. Voir les macros disponibles
cli-anything-macrocli macro list --json

# 2. Inspecter les paramètres d'une macro
cli-anything-macrocli macro info export_file --json

# 3. Test à blanc pour vérifier les paramètres sans effets de bord
cli-anything-macrocli --dry-run macro run export_file \
    --param output=/tmp/test.txt --json

# 4. Exécuter une macro
cli-anything-macrocli macro run export_file \
    --param output=/tmp/result.txt --json

# 5. Voir les backends disponibles
cli-anything-macrocli backends --json

Référence des commandes

Indicateurs globaux

Indicateur	Description
--json	Sortie JSON lisible par machine sur stdout
--dry-run	Simule toutes les étapes, ignore les effets de bord
--session-id <id>	Reprendre ou créer une session nommée

Groupe macro

Commande	Description
macro list	Liste toutes les macros disponibles
macro info <nom>	Affiche le schéma d'une macro (paramètres, étapes, conditions)
macro run <nom> --param clé=valeur	Exécute une macro
macro dry-run <nom> --param clé=valeur	Simulation sans effets de bord
macro validate [nom]	Validation structurelle
macro define <nom>	Génère le squelette d'un fichier YAML de macro

Groupe session

Commande	Description
session status	Affiche les statistiques de la session
session history	Affiche l'historique des exécutions récentes
session save	Persiste la session sur le disque
session list	Liste toutes les sessions sauvegardées

backends

cli-anything-macrocli backends --json
# Affiche : native_api, file_transform, semantic_ui, gui_macro, recovery
# et indique si chacun est disponible dans l'environnement actuel.

Paramètres des macros

Passez les paramètres avec --param clé=valeur. Répétez pour plusieurs paramètres :

cli-anything-macrocli macro run transform_json \
    --param file=/chemin/vers/donnees.json \
    --param key=settings.theme \
    --param value=dark \
    --json

Format de sortie (--json)

Toutes les commandes produisent une sortie JSON lorsque --json est défini :

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

En cas d'échec ("success": false), lisez le champ "error" pour connaître la raison. Le code de sortie est 1 en cas d'échec.

Backends d'exécution

Les backends sont sélectionnés automatiquement en fonction de la définition des étapes de la macro :

Backend	Déclenché par	Cas d'usage
native_api	backend: native_api	Sous-processus / commande shell
file_transform	backend: file_transform	Édition de fichiers XML, JSON, texte
semantic_ui	backend: semantic_ui	Accessibilité / raccourcis clavier
gui_macro	backend: gui_macro	Relecture de coordonnées précompilées
recovery	backend: recovery	Orchestration de nouvelle tentative / repli

Écrire des macros

Les macros sont des fichiers YAML dans cli_anything/macrocli/macro_definitions/. Générez-en une avec :

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

Schéma minimal :

name: my_macro
version: "1.0"
description: Ce que fait cette macro.

parameters:
  output:
    type: string
    required: true
    description: Où écrire les résultats.
    example: /tmp/result.txt

preconditions:
  - file_exists: /chemin/vers/input

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

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

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

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

Règles d'utilisation pour les agents

1. Utilisez toujours --json pour une sortie exploitable par programme.
2. Utilisez --dry-run pour valider les paramètres avant d'exécuter des macros ayant des effets de bord.
3. Vérifiez le champ success — ne supposez pas le succès uniquement d'après le code de sortie.
4. Lisez le champ error lorsque success est faux — il explique la cause de l'échec.
5. Utilisez macro info <nom> pour découvrir les paramètres avant d'appeler macro run.
6. Utilisez des chemins absolus pour tous les paramètres de fichier.

Exemple de flux de travail

# Étape 1 : Qu'est-ce qui est disponible ?
cli-anything-macrocli macro list --json

# Étape 2 : De quels paramètres transform_json a-t-il besoin ?
cli-anything-macrocli macro info transform_json --json

# Étape 3 : Test sécurisé
cli-anything-macrocli --dry-run macro run transform_json \
    --param file=/tmp/config.json \
    --param key=theme \
    --param value=dark --json

# Étape 4 : Exécution réelle
cli-anything-macrocli macro run transform_json \
    --param file=/tmp/config.json \
    --param key=theme \
    --param value=dark --json

Version

1.0.0