# YamlCommandReader Source Code in Maestro: File Location and Implementation Guide

> Locate the YamlCommandReader source code in the Maestro repository. Discover how it parses YAML flow files into executable Command objects with this implementation guide.

- Repository: [Maestro/Maestro](https://github.com/mobile-dev-inc/Maestro)
- Tags: internals
- Published: 2026-03-20

---

**The YamlCommandReader source code is located at [`maestro-orchestra/src/main/java/maestro/orchestra/yaml/YamlCommandReader.kt`](https://github.com/mobile-dev-inc/Maestro/blob/main/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`](https://github.com/mobile-dev-inc/Maestro/blob/main/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:

```kotlin
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()`:

```kotlin
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:

```kotlin
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`](https://github.com/mobile-dev-inc/Maestro/blob/main/YamlCommandReader.kt)** — Core parser converting YAML flow definitions into `Command` objects
- **[`YamlTakeScreenshot.kt`](https://github.com/mobile-dev-inc/Maestro/blob/main/YamlTakeScreenshot.kt)** — Data class representing the `takeScreenshot` command with custom deserialization logic
- **[`YamlSwipe.kt`](https://github.com/mobile-dev-inc/Maestro/blob/main/YamlSwipe.kt)** — Handles swipe-related commands including coordinate and direction parsing
- **[`YamlStopApp.kt`](https://github.com/mobile-dev-inc/Maestro/blob/main/YamlStopApp.kt)** — Represents the `stopApp` command structure and its YAML mapping
- **[`YamlCommandReaderTest.kt`](https://github.com/mobile-dev-inc/Maestro/blob/main/YamlCommandReaderTest.kt)** — Comprehensive unit tests validating parser behavior against diverse YAML flows (located in `maestro-orchestra/src/test/java/maestro/orchestra/yaml/`)
- **[`DeviceService.kt`](https://github.com/mobile-dev-inc/Maestro/blob/main/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`](https://github.com/mobile-dev-inc/Maestro/blob/main/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`](https://github.com/mobile-dev-inc/Maestro/blob/main/YamlCommandReaderTest.kt)
- The Maestro Studio server utilizes this reader in [`DeviceService.kt`](https://github.com/mobile-dev-inc/Maestro/blob/main/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`](https://github.com/mobile-dev-inc/Maestro/blob/main/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`](https://github.com/mobile-dev-inc/Maestro/blob/main/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`](https://github.com/mobile-dev-inc/Maestro/blob/main/DeviceService.kt)), demonstrating its utility as a standalone parser for YAML automation commands in server environments or custom integrations.