YamlCommandReader Source Code in Maestro: File Location and Implementation Guide

The YamlCommandReader source code is located at maestro-orchestra/src/main/java/maestro/orchestra/yaml/YamlCommandReader.kt in the mobile-dev-inc/Maestro repository, where it parses YAML flow files into executable Command objects.

The YamlCommandReader serves as the core parser engine for Maestro's mobile UI automation framework, transforming declarative YAML scripts into runnable commands. Located within the Orchestra module of the mobile-dev-inc/Maestro repository, this Kotlin class bridges the gap between human-readable flow definitions and the framework's internal execution model.

Core File Location

The primary YamlCommandReader implementation resides in the Orchestra module under the following path:

• maestro-orchestra/src/main/java/maestro/orchestra/yaml/YamlCommandReader.kt

This class acts as the main entry point for deserializing Maestro flow files, handling the conversion of YAML syntax into strongly-typed Command objects used throughout the automation engine. According to the Maestro source code, the reader supports both complete file parsing and ad-hoc command interpretation for dynamic scenarios.

Key Methods and Usage Patterns

The YamlCommandReader exposes static utility methods for parsing different YAML input types. These methods enable integration points for CLI tools, server components, and test harnesses.

Reading Complete Flow Files

Use readCommands() to parse an entire .yaml flow file from disk into a list of executable commands:

import maestro.orchestra.yaml.YamlCommandReader
import java.nio.file.Paths

val flowPath = Paths.get("path/to/your/flow.yaml")
val commands = YamlCommandReader.readCommands(flowPath)

Parsing Single Commands

For dynamic inputs such as API payloads or REPL interactions, use readSingleCommand():

val singleCommand = YamlCommandReader.readSingleCommand(
    basePath = Paths.get(""),
    fileName = "",
    yaml = "tapOn: \"Login\""
)

Formatting and Serialization

The reader also provides reverse serialization capabilities via formatCommands(), enabling pretty-printing of command lists back to YAML format:

val yamlString = YamlCommandReader.formatCommands(commands)
println(yamlString)

Related Source Files in the Yaml Package

The YAML parsing ecosystem spans several coordinated files within maestro-orchestra/src/main/java/maestro/orchestra/yaml/:

• YamlCommandReader.kt — Core parser converting YAML flow definitions into Command objects
• YamlTakeScreenshot.kt — Data class representing the takeScreenshot command with custom deserialization logic
• YamlSwipe.kt — Handles swipe-related commands including coordinate and direction parsing
• YamlStopApp.kt — Represents the stopApp command structure and its YAML mapping
• YamlCommandReaderTest.kt — Comprehensive unit tests validating parser behavior against diverse YAML flows (located in maestro-orchestra/src/test/java/maestro/orchestra/yaml/)
• DeviceService.kt — Reference implementation in Maestro Studio server (maestro-studio/server/src/main/java/maestro/studio/) demonstrating runtime usage of the reader for handling incoming command payloads

Summary

• The YamlCommandReader source code is located at maestro-orchestra/src/main/java/maestro/orchestra/yaml/YamlCommandReader.kt in the mobile-dev-inc/Maestro repository
• Use readCommands() to parse complete flow files and readSingleCommand() for inline YAML strings or API payloads
• The formatCommands() method enables round-trip serialization from Command objects back to YAML text
• Command-specific data classes (YamlSwipe, YamlTakeScreenshot, etc.) reside in the same package with corresponding test coverage in YamlCommandReaderTest.kt
• The Maestro Studio server utilizes this reader in DeviceService.kt for handling dynamic command execution in server environments

Frequently Asked Questions

What is the exact file path for the YamlCommandReader in the Maestro repository?

The YamlCommandReader is located at maestro-orchestra/src/main/java/maestro/orchestra/yaml/YamlCommandReader.kt within the mobile-dev-inc/Maestro repository. This Kotlin file contains the main class responsible for parsing YAML automation flows into Maestro's internal command representation.

How does YamlCommandReader convert YAML files to Command objects?

The reader uses static methods like readCommands() and readSingleCommand() to deserialize YAML content into Maestro's internal Command representations. It processes Maestro-specific syntax including commands like tapOn, swipe, and takeScreenshot through dedicated data classes in the same package that handle custom deserialization logic.

Are there unit tests available for the YamlCommandReader?

Yes, comprehensive test coverage exists in maestro-orchestra/src/test/java/maestro/orchestra/yaml/YamlCommandReaderTest.kt. This test file exercises the parser against various YAML flow configurations to ensure correct deserialization, error handling, and edge case management.

Can YamlCommandReader be used outside of the Maestro CLI?

Yes, the class is utilized independently in other Maestro components such as the Maestro Studio server (DeviceService.kt), demonstrating its utility as a standalone parser for YAML automation commands in server environments or custom integrations.

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