maa-cli-operate

Maa CLI Operate

Use the pinned external maafw-cli runtime. Read references/command-contract.md before composing commands or interpreting output.

Choose the runtime

Use maafw-cli for one-shot, repeatable operations with compact JSON output: device discovery, resource checks, Pipeline validation, scripted recognition/action sequences, and CI jobs.

Use MaaMCP instead when the task benefits from a long-lived exploratory session, repeated visual inspection, interactive Pipeline debugging, or an MCP-native tool schema. Do not run both against the same device session unless the user deliberately wants separate controllers.

Prepare safely

1. Run the pinned version check and require the tested version.
2. Use --json for every non-help operation that supports it. Parse stdout as JSON; keep stderr for diagnostics.
3. Check resource status before OCR. Treat download-ocr as an explicit network and disk mutation.
4. Discover devices before connecting. Resolve an exact ADB address, Win32 title/handle, PlayCover application, or wlroots target instead of guessing.
5. Use a named --on session whenever more than one command or device is involved. Record whether the daemon or session existed before the task.

Validate and run Pipeline

1. Run pipeline validate PATH before loading or executing a Pipeline.
2. Inspect the returned nodes and resolve the intended entry explicitly when more than one entry is plausible.
3. Use pipeline load and pipeline show NODE for inspection without task execution.
4. Use pipeline run PATH ENTRY only after the controller, resource paths, entry node, and expected device effects are known.
5. Pass runtime overrides as one valid JSON object through --override. Do not rewrite source Pipeline files for a temporary runtime change.
6. Route Pipeline authoring problems to $maa-pipeline-guide, graph questions to $maa-pipeline-graph, and behavior validation to $maa-pipeline-testing.

Observe, act, verify