MacroCLI CLI
개요
MacroCLI는 가치 있는 GUI 워크플로우를 파라미터화된 CLI 호출 가능 매크로로 변환합니다. 에이전트는 GUI에 직접 접근하지 않고 안정적인 CLI를 통해 매크로를 호출하며, 런타임은 최적의 백엔드(네이티브 플러그인/API, 파일 변환, 시맨틱 UI 제어, 또는 사전 컴파일된 GUI 매크로 재생)로 실행을 라우팅합니다.
설치
cd macrocli/agent-harness
pip install -e .
요구 사항: Python 3.10+, PyYAML, click, prompt-toolkit.
빠른 시작 (에이전트용)
# 1. 사용 가능한 매크로 확인
cli-anything-macrocli macro list --json
# 2. 매크로 파라미터 검사
cli-anything-macrocli macro info export_file --json
# 3. 부작용 없이 파라미터 확인을 위한 드라이런
cli-anything-macrocli --dry-run macro run export_file \
--param output=/tmp/test.txt --json
# 4. 매크로 실행
cli-anything-macrocli macro run export_file \
--param output=/tmp/result.txt --json
# 5. 사용 가능한 백엔드 확인
cli-anything-macrocli backends --json
명령어 참조
전역 플래그
| 플래그 | 설명 |
|---|---|
--json | 기계가 읽을 수 있는 JSON 출력을 stdout으로 출력 |
--dry-run | 모든 단계를 시뮬레이션하고 부작용은 건너뜀 |
--session-id <id> | 명명된 세션을 재개하거나 생성 |
macro 그룹
| 명령어 | 설명 |
|---|---|
macro list | 사용 가능한 모든 매크로 나열 |
macro info <name> | 매크로 스키마(파라미터, 단계, 조건) 표시 |
macro run <name> --param k=v | 매크로 실행 |
macro dry-run <name> --param k=v | 부작용 없이 시뮬레이션 |
macro validate [name] | 구조 유효성 검사 |
macro define <name> | 새 매크로 YAML 스캐폴딩 |
session 그룹
| 명령어 | 설명 |
|---|---|
session status | 세션 통계 표시 |
session history | 최근 실행 기록 표시 |
session save | 세션을 디스크에 저장 |
session list | 저장된 모든 세션 나열 |
backends
cli-anything-macrocli backends --json
# 출력: native_api, file_transform, semantic_ui, gui_macro, recovery
# 및 각각이 현재 환경에서 사용 가능한지 여부.
매크로 파라미터
--param key=value로 파라미터를 전달합니다. 여러 개는 반복합니다:
cli-anything-macrocli macro run transform_json \
--param file=/path/to/data.json \
--param key=settings.theme \
--param value=dark \
--json
출력 형식 (--json)
--json이 설정되면 모든 명령어가 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
}
}
실패 시("success": false), "error" 필드에서 이유를 확인하세요. 종료 코드는 실패 시 1입니다.
실행 백엔드
백엔드는 매크로 단계 정의에 따라 자동으로 선택됩니다:
| 백엔드 | 트리거 | 사용 사례 |
|---|---|---|
native_api | backend: native_api | 서브프로세스 / 셸 명령어 |
file_transform | backend: file_transform | XML, JSON, 텍스트 파일 편집 |
semantic_ui | backend: semantic_ui | 접근성 / 키보드 단축키 |
gui_macro | backend: gui_macro | 사전 컴파일된 좌표 재생 |
recovery | backend: recovery | 재시도 / 폴백 오케스트레이션 |
매크로 작성
매크로는 cli_anything/macrocli/macro_definitions/ 디렉토리의 YAML 파일입니다. 다음 명령어로 스캐폴딩하세요:
cli-anything-macrocli macro define my_macro --output \
cli_anything/macrocli/macro_definitions/examples/my_macro.yaml
최소 스키마:
name: my_macro
version: "1.0"
description: 이 매크로가 수행하는 작업.
parameters:
output:
type: string
required: true
description: 결과를 쓸 위치.
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 # 또는: 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
에이전트 사용 규칙
- 프로그래매틱 출력을 위해 항상
--json을 사용하세요. - 부작용이 있는 매크로를 실행하기 전에
--dry-run으로 파라미터를 검증하세요. success필드를 확인하세요 — 종료 코드만으로 성공을 가정하지 마세요.success가 false일 때error필드를 읽어 무엇이 실패했는지 확인하세요.macro run을 호출하기 전에macro info <name>으로 파라미터를 확인하세요.- 모든 파일 파라미터에 절대 경로를 사용하세요.
예제 워크플로우
# 1단계: 무엇이 가능한가?
cli-anything-macrocli macro list --json
# 2단계: transform_json에 어떤 파라미터가 필요한가?
cli-anything-macrocli macro info transform_json --json
# 3단계: 안전하게 테스트
cli-anything-macrocli --dry-run macro run transform_json \
--param file=/tmp/config.json \
--param key=theme \
--param value=dark --json
# 4단계: 실제 실행
cli-anything-macrocli macro run transform_json \
--param file=/tmp/config.json \
--param key=theme \
--param value=dark --json
버전
1.0.0