cli-anything-macrocli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MacroCLI CLI

What It Is

是什么

The MacroCLI converts valuable GUI workflows into parameterized, CLI-callable macros. Agents never touch the GUI directly — they call macros through this stable CLI, and the runtime routes execution to the best available backend (native plugin/API, file transformation, semantic UI control, or precompiled GUI macro replay).

MacroCLI 可将有价值的GUI工作流转换为可参数化、可通过CLI调用的宏。Agent永远不会直接操作GUI——它们通过这个稳定的CLI调用宏，运行时会将执行路由到最佳可用后端（原生插件/API、文件转换、语义UI控件或预编译的GUI宏重放）。

Installation

安装

bash

cd macrocli/agent-harness
pip install -e .

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

bash

cd macrocli/agent-harness
pip install -e .

要求： Python 3.10+、PyYAML、click、prompt-toolkit。

Quick Start (for agents)

快速入门（面向Agent）

bash

undefined

bash

undefined

1. See what macros are available

cli-anything-macrocli macro list --json

2. Inspect a macro's parameters

cli-anything-macrocli macro info export_file --json

3. Dry-run to check params without side effects

cli-anything-macrocli --dry-run macro run export_file
--param output=/tmp/test.txt --json

4. Execute a macro

cli-anything-macrocli macro run export_file
--param output=/tmp/result.txt --json

5. See what backends are available

cli-anything-macrocli backends --json

undefined

cli-anything-macrocli backends --json

undefined

Command Reference

命令参考

Global Flags

全局标志

Flag	Description
`--json`	Machine-readable JSON output on stdout
`--dry-run`	Simulate all steps, skip side effects
`--session-id <id>`	Resume or create a named session

标志	描述
`--json`	在标准输出中生成机器可读的JSON格式输出
`--dry-run`	模拟所有步骤，跳过副作用操作
`--session-id <id>`	恢复或创建一个命名会话

macro

group

macro

命令组

Command	Description
`macro list`	List all available macros
`macro info <name>`	Show macro schema (parameters, steps, conditions)
`macro run <name> --param k=v`	Execute a macro
`macro dry-run <name> --param k=v`	Simulate without side effects
`macro validate [name]`	Structural validation
`macro define <name>`	Scaffold a new macro YAML

命令	描述
`macro list`	列出所有可用宏
`macro info <name>`	显示宏的Schema（参数、步骤、条件）
`macro run <name> --param k=v`	执行宏
`macro dry-run <name> --param k=v`	模拟执行，无副作用
`macro validate [name]`	结构验证
`macro define <name>`	生成新宏的YAML模板

session

group

session

命令组

Command	Description
`session status`	Show session statistics
`session history`	Show recent run history
`session save`	Persist session to disk
`session list`	List all saved sessions

命令	描述
`session status`	显示会话统计信息
`session history`	显示近期运行历史
`session save`	将会话持久化到磁盘
`session list`	列出所有已保存的会话

backends

backends

bash

cli-anything-macrocli backends --json

bash

cli-anything-macrocli backends --json

Shows: native_api, file_transform, semantic_ui, gui_macro, recovery

and whether each is available in the current environment.

undefined

undefined

Macro Parameters

宏参数

Pass parameters with

--param key=value

. Repeat for multiple:

bash

cli-anything-macrocli macro run transform_json \
    --param file=/path/to/data.json \
    --param key=settings.theme \
    --param value=dark \
    --json

使用

--param key=value

传递参数，多个参数可重复使用：

bash

cli-anything-macrocli macro run transform_json \
    --param file=/path/to/data.json \
    --param key=settings.theme \
    --param value=dark \
    --json

Output Format (--json)

输出格式（--json）

All commands output JSON when

--json

is set:

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

On failure (

"success": false

), read the

"error"

field for the reason. Exit code is 1 on failure.

当设置

--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。

Execution Backends

执行后端

Backends are selected automatically based on the macro step definition:

Backend	Triggered by	Use case
`native_api`	`backend: native_api`	Subprocess / shell command
`file_transform`	`backend: file_transform`	XML, JSON, text file editing
`semantic_ui`	`backend: semantic_ui`	Accessibility / keyboard shortcuts
`gui_macro`	`backend: gui_macro`	Precompiled coordinate replay
`recovery`	`backend: recovery`	Retry / fallback orchestration

后端会根据宏步骤定义自动选择：

后端	触发条件	使用场景
`native_api`	`backend: native_api`	子进程/Shell命令
`file_transform`	`backend: file_transform`	XML、JSON、文本文件编辑
`semantic_ui`	`backend: semantic_ui`	无障碍访问/键盘快捷键
`gui_macro`	`backend: gui_macro`	预编译坐标重放
`recovery`	`backend: recovery`	重试/ fallback编排

Writing Macros

编写宏

Macros are YAML files in

cli_anything/macrocli/macro_definitions/

. Scaffold one with:

bash

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

Minimal schema:

yaml

name: my_macro
version: "1.0"
description: What this macro does.

parameters:
  output:
    type: string
    required: true
    description: Where to write results.
    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  # or: 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

宏是位于

cli_anything/macrocli/macro_definitions/

目录下的YAML文件。可以通过以下命令快速生成一个模板：

bash

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

最小化Schema：

yaml

name: my_macro
version: "1.0"
description: What this macro does.

parameters:
  output:
    type: string
    required: true
    description: Where to write results.
    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  # or: 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

Agent Usage Rules

Agent 使用规则

Always use
--json
for programmatic output.
Use
--dry-run
to validate params before executing side-effectful macros.
Check
success
field — do not assume success from exit code alone.
Read
error
field when
```
success
```
is false — it explains what failed.
Use
macro info <name>
to discover params before calling
```
macro run
```
.
Use absolute paths for all file parameters.

**始终使用
```
--json
```
**以获取程序化输出。
执行有副作用的宏之前，使用
--dry-run
验证参数。
检查
success
字段——不要仅通过退出码判断是否成功。
当
success
为false时，查看
error
字段——它会解释失败原因。
调用
macro run
之前，使用
macro info <name>
了解参数。
所有文件参数都使用绝对路径。

Example Workflow

示例工作流

bash

undefined

bash

undefined

Step 1: What's available?

cli-anything-macrocli macro list --json

Step 2: What params does transform_json need?

cli-anything-macrocli macro info transform_json --json

Step 3: Test safely

cli-anything-macrocli --dry-run macro run transform_json
--param file=/tmp/config.json
--param key=theme
--param value=dark --json

Step 4: Execute for real

cli-anything-macrocli macro run transform_json
--param file=/tmp/config.json
--param key=theme
--param value=dark --json

undefined

cli-anything-macrocli macro run transform_json
--param file=/tmp/config.json
--param key=theme
--param value=dark --json

undefined

Version

版本

1.0.0