MacroCLI CLI

O que MacroCLI CLI faz?

O Que É

O MacroCLI converte fluxos de trabalho GUI valiosos em macros parametrizadas, invocáveis por CLI. Agentes nunca tocam no GUI diretamente — eles chamam macros por meio desta CLI estável, e o runtime roteia a execução para o melhor backend disponível (plugin/API nativa, transformação de arquivos, controle de interface semântico, ou reprodução de macro GUI pré-compilada).

Instalação

cd macrocli/agent-harness
pip install -e .

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

Início Rápido (para agentes)

# 1. Veja quais macros estão disponíveis
cli-anything-macrocli macro list --json

# 2. Inspecione os parâmetros de uma macro
cli-anything-macrocli macro info export_file --json

# 3. Dry-run para verificar parâmetros sem efeitos colaterais
cli-anything-macrocli --dry-run macro run export_file \
    --param output=/tmp/test.txt --json

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

# 5. Veja quais backends estão disponíveis
cli-anything-macrocli backends --json

Referência de Comandos

Flags Globais

Flag	Descrição
--json	Saída JSON legível por máquina no stdout
--dry-run	Simula todas as etapas, ignora efeitos colaterais
--session-id <id>	Retoma ou cria uma sessão nomeada

Grupo macro

Comando	Descrição
macro list	Lista todas as macros disponíveis
macro info <name>	Exibe o esquema da macro (parâmetros, etapas, condições)
macro run <name> --param k=v	Executa uma macro
macro dry-run <name> --param k=v	Simula sem efeitos colaterais
macro validate [name]	Validação estrutural
macro define <name>	Cria um esqueleto para um novo arquivo YAML de macro

Grupo session

Comando	Descrição
session status	Exibe estatísticas da sessão
session history	Exibe histórico recente de execuções
session save	Persiste a sessão no disco
session list	Lista todas as sessões salvas

backends

cli-anything-macrocli backends --json
# Mostra: native_api, file_transform, semantic_ui, gui_macro, recovery
# e se cada um está disponível no ambiente atual.

Parâmetros de Macro

Passe parâmetros com --param chave=valor. Repita para múltiplos:

cli-anything-macrocli macro run transform_json \
    --param file=/caminho/para/dados.json \
    --param key=config.tema \
    --param value=escuro \
    --json

Formato de Saída (--json)

Todos os comandos produzem saída JSON quando --json é definido:

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

Em caso de falha ("success": false), leia o campo "error" para a razão. O código de saída é 1 em caso de falha.

Backends de Execução

Os backends são selecionados automaticamente com base na definição da etapa da macro:

Backend	Acionado por	Caso de uso
native_api	backend: native_api	Subprocesso / comando shell
file_transform	backend: file_transform	Edição de XML, JSON, arquivos de texto
semantic_ui	backend: semantic_ui	Acessibilidade / atalhos de teclado
gui_macro	backend: gui_macro	Reprodução de coordenadas pré-compiladas
recovery	backend: recovery	Orquestração de repetição / fallback

Escrevendo Macros

As macros são arquivos YAML em cli_anything/macrocli/macro_definitions/. Crie um esqueleto com:

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

Esquema mínimo:

name: minha_macro
version: "1.0"
description: O que esta macro faz.

parameters:
  output:
    type: string
    required: true
    description: Onde escrever os resultados.
    example: /tmp/result.txt

preconditions:
  - file_exists: /caminho/para/entrada

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

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

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

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

Regras de Uso para Agentes

1. Sempre use --json para saída programática.
2. Use --dry-run para validar parâmetros antes de executar macros com efeitos colaterais.
3. Verifique o campo success — não presuma sucesso apenas pelo código de saída.
4. Leia o campo error quando success for false — ele explica o que falhou.
5. Use macro info <nome> para descobrir parâmetros antes de chamar macro run.
6. Use caminhos absolutos para todos os parâmetros de arquivo.

Exemplo de Fluxo de Trabalho

# Etapa 1: O que está disponível?
cli-anything-macrocli macro list --json

# Etapa 2: Quais parâmetros o transform_json precisa?
cli-anything-macrocli macro info transform_json --json

# Etapa 3: Teste com segurança
cli-anything-macrocli --dry-run macro run transform_json \
    --param file=/tmp/config.json \
    --param key=tema \
    --param value=escuro --json

# Etapa 4: Execute de verdade
cli-anything-macrocli macro run transform_json \
    --param file=/tmp/config.json \
    --param key=tema \
    --param value=escuro --json

Versão

1.0.0