How to Use Anchors and Aliases in Maestro YAML: A Complete Guide

Anchors and aliases in Maestro YAML let you define reusable configuration blocks using the & anchor syntax and reference them anywhere with the * alias syntax, eliminating repetitive code in your mobile UI automation flows.

Maestro flow files leverage standard YAML syntax parsed by Jackson's YAMLFactory (which uses SnakeYAML under the hood). Because the mobile-dev-inc/Maestro repository relies on these industry-standard parsers, the full YAML 1.2 specification—including anchors and aliases—is supported automatically without any custom implementation.

What Are Anchors and Aliases in Maestro YAML?

In standard YAML syntax, an anchor (&) marks a specific node with a name, while an alias (*) retrieves and inserts that named node elsewhere in the document. This mechanism allows you to write a block once and reuse it multiple times, keeping your Maestro flows DRY (Don't Repeat Yourself).

Maestro does not implement custom logic for these features. Instead, the parser in maestro-orchestra/src/main/java/maestro/orchestra/yaml/MaestroFlowParser.kt relies on Jackson's ObjectMapper with YAMLFactory to resolve anchors and aliases automatically during the initial parsing phase.

How Maestro Parses Anchors and Aliases

The resolution occurs before Maestro's command processing begins. In MaestroFlowParser.kt (lines 52-56), the codebase initializes the mapper:

// ObjectMapper creation with YAML support
val mapper = ObjectMapper(YAMLFactory())
mapper.registerModule(KotlinModule.Builder().build())

When the parser reads a flow file (lines 61-68), this mapper automatically expands all anchors and aliases into a fully materialized object graph. By the time the data reaches YamlCommandReader and is mapped to YamlFluentCommand objects, no anchor syntax remains. The rest of Maestro's pipeline—including command validation and execution—operates on the resolved data structure.

Practical Examples of Anchors and Aliases in Maestro

Reusing Selector Definitions

Define a selector once and reference it for multiple commands:

# Define the selector once and give it an anchor name "loginBtn"

loginBtn: &loginBtn
  text: "Log In"
  optional: true

# Use the same selector for two separate tap actions via alias

- tapOn: *loginBtn
- assertVisible: *loginBtn

Sharing Complex Command Blocks

Anchor entire command configurations to ensure consistency across steps:

# Anchor a whole command (including options)

launchConfig: &launchConfig
  appId: com.example.myapp
  clearState: true
  permissions:
    - CAMERA
    - LOCATION

# Reference the anchored block wherever a launch is needed

- launchApp: *launchConfig
- runFlow:
    file: anotherFlow.yaml
    config:
      appId: com.example.myapp
      # Re-use the same launch configuration

      launchApp: *launchConfig

Anchoring Configuration Sections

Use anchors in the config section to share headers or environment settings:

# Config section can also benefit from anchors

config:
  url: https://example.com
  headers: &commonHeaders
    Authorization: Bearer ${TOKEN}
    Accept: application/json

# Later use the same headers for a request

- httpRequest:
    method: GET
    path: /api/data
    headers: *commonHeaders

Summary

• Anchors and aliases are standard YAML features fully supported in Maestro through Jackson's YAMLFactory (SnakeYAML).
• Resolution happens early: MaestroFlowParser.kt resolves all aliases during parsing, before commands are mapped to YamlFluentCommand objects.
• Use cases include deduplicating selectors, sharing complex command configurations, and reusing header definitions.
• No custom syntax is required; simply use & to define anchors and * to reference them anywhere within the same YAML document.

Frequently Asked Questions

Can I use anchors across separate Maestro flow files?

No. YAML anchors and aliases are document-scoped according to the YAML specification. Since Maestro uses standard SnakeYAML parsing as implemented in MaestroFlowParser.kt, each flow file is parsed independently, and anchors defined in one file cannot be referenced via aliases in another.

Are anchors resolved before Maestro validates command syntax?

Yes. According to the source code in MaestroFlowParser.kt (lines 61-68), the Jackson ObjectMapper resolves all anchors and aliases during the initial YAML parsing phase. This means by the time the data reaches YamlCommandReader and is mapped to YamlFluentCommand objects, the anchor syntax has already been expanded into a fully materialized object graph.

Can I anchor complex nested structures like entire command blocks?

Absolutely. As demonstrated in the mobile-dev-inc/Maestro source examples, you can anchor entire command configurations—including nested maps and lists—and reference them via aliases. The parser handles arbitrary YAML node types, allowing you to share complex launchApp configurations or selector definitions across multiple steps.

Do anchors work within Maestro's global config section?

Yes. The config section in Maestro flows follows standard YAML syntax, so anchors work there just as they do in command sections. You can define anchored header sets or environment configurations in the config block and reference them elsewhere in the same file, reducing duplication in your flow definitions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}