# How the Auth0 Deploy CLI Context Parser Works with YAML vs Directory Formats

> Understand how Auth0 Deploy CLI context parsers handle YAML and directory formats, normalizing data for a seamless tenant deployment pipeline.

- Repository: [Auth0/auth0-deploy-cli](https://github.com/auth0/auth0-deploy-cli)
- Tags: internals
- Published: 2026-02-25

---

**The Auth0 Deploy CLI abstracts tenant definitions behind two concrete context parsers—`YAMLContext` for single-file configurations and `DirectoryContext` for folder-based structures—normalizing both formats into a common asset pipeline for deployment.**

The auth0/auth0-deploy-cli repository enables infrastructure-as-code management for Auth0 tenants, supporting both consolidated YAML files and distributed directory layouts. The context parser architecture decouples the storage format from the deployment logic, allowing the same validation, change calculation, and deployment pipeline to operate regardless of input type. Understanding how these parsers handle different data formats reveals the CLI's extensibility and consistent handling of keywords, read-only fields, and identifiers.

## Core Context Parser Architecture

The Deploy CLI shields the deployment engine from input format specifics through a unified abstraction layer. Two concrete implementations handle distinct storage patterns while exposing an identical interface to the rest of the application:

- **YAML Context** ([`src/context/yaml/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/yaml/index.ts)): Processes single YAML or JSON files containing the entire tenant definition
- **Directory Context** ([`src/context/directory/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/directory/index.ts)): Processes root folders containing one JSON file per resource type

Both parsers receive the CLI `Config` object and an Auth0 `ManagementClient` during construction. They store the input location (`config.AUTH0_INPUT_FILE`), keyword-mapping tables, and a paged client wrapper (`pagedClient`) for API interactions.

## YAML Context Parser Implementation

Located in [`src/context/yaml/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/yaml/index.ts), the YAML context parser manages monolithic configuration files through a read-modify-write workflow.

### Loading Assets from YAML

The `loadAssetsFromLocal` method performs the initial ingestion:

1. Reads the entire file contents
2. Processes content through `keywordReplace` (or `wrapArrayReplaceMarkersInQuotes` when keyword replacement is disabled)
3. Loads the result into `this.assets`
4. Iterates over handlers in `src/context/yaml/handlers/*`, merging additional data each handler returns

YAML handlers further materialize nested assets, such as loading external rule files referenced within the main configuration.

### Exporting to YAML

During the `dump` operation for exports, the parser:

1. Instantiates the `Auth0` helper from [`src/tools/auth0/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/tools/auth0/index.ts) to fetch remote assets via the Management API
2. Optionally preserves raw keyword markers when `AUTH0_PRESERVE_KEYWORDS` is enabled
3. Cleans read-only fields using logic from [`src/readonly.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/readonly.ts)
4. Strips identifiers via `stripIdentifiers` in [`src/utils.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/utils.ts)
5. Writes the final output using `yaml.dump` to produce a single file

## Directory Context Parser Implementation

The directory parser in [`src/context/directory/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/directory/index.ts) handles distributed configurations where resources reside across multiple JSON files in a folder hierarchy.

### Loading Assets from Directory

The `loadAssetsFromLocal` method operates differently than its YAML counterpart:

1. Validates that `config.AUTH0_INPUT_FILE` points to a directory
2. Synchronously invokes each handler's `parse(this)` method from `src/context/directory/handlers/*`
3. Merges results from handlers, which independently read their specific JSON files

Unlike the YAML parser, this implementation does not read a single master file; instead, each handler owns the file I/O for its resource type.

### Exporting to Directory

The export workflow mirrors the YAML context but distributes output:

1. Fetches remote assets through the `Auth0` helper
2. Processes keyword preservation, read-only field cleaning, and identifier stripping using the same utilities as YAML
3. Writes one file per resource type, with each handler's `dump` method determining the exact filename and location within the folder hierarchy

The parser also copies auxiliary data such as clients and user-attribute-profiles during this process.

## Shared Workflow and Keyword Handling

Both parsers utilize common utilities in [`src/tools/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/tools/index.ts) for consistent cross-format behavior.

### Keyword Replacement Logic

When loading nested files, both parsers invoke `loadFileAndReplaceKeywords`. If the user sets `AUTH0_PRESERVE_KEYWORDS`, the parsers first disable replacement by setting `disableKeywordReplacement: true` to capture raw markers (e.g., `##KEYWORD##`) before merging with remote assets. The merging logic resides in [`src/keywordPreservation.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/keywordPreservation.ts), ensuring that keyword markers survive round-trip export/import cycles regardless of storage format.

### Common Export Pipeline

Both formats follow identical export steps:

- Instantiate the `Auth0` helper to contact the Management API
- Load all remote assets through the same handler collection
- Optionally preserve raw keyword markers
- Clean read-only properties via [`src/readonly.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/readonly.ts)
- Strip identifiers using `stripIdentifiers` from [`src/utils.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/utils.ts)

## Handler Pattern Architecture

Both contexts implement the same handler interface, enabling format-agnostic resource management while keeping parser implementations clean.

### Handler Responsibilities

Each handler, located in either `src/context/yaml/handlers` or `src/context/directory/handlers`, implements:

- **`parse(context)`**: Reads the source (single YAML file or multiple JSON files) and returns an object keyed by resource type
- **`dump(context)`**: Receives remote assets and writes them to the appropriate location (single file or directory)

Because handlers are separated by format but share interface contracts, the parsers remain agnostic of concrete storage details while reusing Auth0 business logic.

## Practical Usage Examples

Export a tenant to a single YAML file:

```bash
npm run build && node lib/index.js export \
  -c config-dev.json \
  -f yaml \
  -o ./tenant.yaml

```

Import the YAML file back into a tenant:

```bash
npm run build && node lib/index.js import \
  -c config-dev.json \
  -i ./tenant.yaml

```

Export a tenant to a directory structure:

```bash
npm run build && node lib/index.js export \
  -c config-dev.json \
  -f directory \
  -o ./local/

```

Import the directory back into a tenant:

```bash
npm run build && node lib/index.js import \
  -c config-dev.json \
  -i ./local/

```

In the first pair, the CLI instantiates `YAMLContext`; in the second, it creates `DirectoryContext`. The remaining pipeline (validation, change calculation, deployment) remains identical.

## Summary

- The Deploy CLI uses `YAMLContext` ([`src/context/yaml/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/yaml/index.ts)) for single-file YAML/JSON inputs and `DirectoryContext` ([`src/context/directory/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/directory/index.ts)) for folder-based configurations
- Both parsers implement `loadAssetsFromLocal` and `dump` methods that normalize different storage formats into a common asset object
- Keyword preservation relies on [`src/keywordPreservation.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/keywordPreservation.ts) and `loadFileAndReplaceKeywords` from [`src/tools/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/tools/index.ts), supporting `AUTH0_PRESERVE_KEYWORDS` across both formats
- Handlers in `src/context/yaml/handlers` and `src/context/directory/handlers` implement format-specific I/O while sharing business logic
- Export operations in both parsers use [`src/readonly.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/readonly.ts) to clean read-only fields and [`src/utils.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/utils.ts) for identifier stripping

## Frequently Asked Questions

### What is the primary difference between the YAML and Directory context parsers?

The YAML context parser in [`src/context/yaml/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/yaml/index.ts) reads a single consolidated file and delegates to YAML-specific handlers, while the Directory context parser in [`src/context/directory/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/directory/index.ts) walks a folder tree and delegates to directory-specific handlers that each manage their own JSON files. Both produce the same internal asset representation, but the YAML parser uses `yaml.dump` for exports whereas the Directory parser writes multiple files via handler `dump` methods.

### How does keyword preservation work across both formats?

When `AUTH0_PRESERVE_KEYWORDS` is enabled, both parsers set `disableKeywordReplacement: true` to capture raw markers like `##KEYWORD##` before merging with remote assets. The logic in [`src/keywordPreservation.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/keywordPreservation.ts) handles the merging, ensuring that keyword placeholders survive round-trip operations whether stored in a single YAML file or distributed across a directory structure.

### Can I switch between YAML and Directory formats for the same tenant?

Yes. Because both parsers normalize inputs into the same asset structure and use identical `Auth0` helper classes from [`src/tools/auth0/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/tools/auth0/index.ts), you can export to YAML and later import from Directory (or vice versa) without data loss. The CLI instantiates the appropriate parser based on the `-f` flag, while the deployment pipeline remains format-agnostic.

### Where is the logic for stripping identifiers and read-only fields?

Both parsers use [`src/readonly.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/readonly.ts) to remove read-only properties from exported assets and `stripIdentifiers` from [`src/utils.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/utils.ts) to remove system-generated IDs. These utilities are called during the `dump` phase in both [`src/context/yaml/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/yaml/index.ts) and [`src/context/directory/index.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/directory/index.ts), ensuring consistent data cleaning regardless of the output format.