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

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): Processes single YAML or JSON files containing the entire tenant definition
• Directory Context (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, 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 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
4. Strips identifiers via stripIdentifiers in 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 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 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, 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
• Strip identifiers using stripIdentifiers from 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:

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:

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

Export a tenant to a directory structure:

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

Import the directory back into a tenant:

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) for single-file YAML/JSON inputs and DirectoryContext (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 and loadFileAndReplaceKeywords from 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 to clean read-only fields and 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 reads a single consolidated file and delegates to YAML-specific handlers, while the Directory context parser in 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 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, 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 to remove read-only properties from exported assets and stripIdentifiers from src/utils.ts to remove system-generated IDs. These utilities are called during the dump phase in both src/context/yaml/index.ts and src/context/directory/index.ts, ensuring consistent data cleaning regardless of the output format.

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