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