How to Specify Connection Directories for Deployment Using AUTH0_CONNECTIONS_DIRECTORY

Set the AUTH0_CONNECTIONS_DIRECTORY environment variable or JSON configuration property to override the default connections folder path used during Auth0 Deploy CLI import and export operations.

The auth0/auth0-deploy-cli tool provides the AUTH0_CONNECTIONS_DIRECTORY configuration option to customize where connection assets are stored within your directory-based deployment context. By default, the CLI reads from and writes to a folder named connections, but you can redirect this to any custom directory structure that fits your project organization.

How AUTH0_CONNECTIONS_DIRECTORY Works

The Deploy CLI resolves the connection directory through a simple fallback mechanism implemented in src/context/directory/handlers/connections.ts (lines 26-28).

The handler first checks for your custom configuration value, then falls back to the built-in constant:

// src/context/directory/handlers/connections.ts
const connectionDirectory =
  context.config.AUTH0_CONNECTIONS_DIRECTORY ||
  constants.CONNECTIONS_DIRECTORY;   // default = 'connections'

If AUTH0_CONNECTIONS_DIRECTORY is undefined or empty, the CLI uses the default value defined in src/tools/constants.ts (line 106), which is hardcoded as 'connections'.

The configuration interface in src/types.ts (line 79) declares this property as optional:

export interface Config {
  // …
  AUTH0_CONNECTIONS_DIRECTORY?: string;   // optional override
}

This typing allows you to specify the directory path as a string value without breaking existing configurations that rely on the default behavior.

Configuration Methods

You can define AUTH0_CONNECTIONS_DIRECTORY through two primary mechanisms depending on your deployment workflow.

Environment Variable

Set the variable in your shell session or .env file to affect the current execution context:

export AUTH0_CONNECTIONS_DIRECTORY=custom-connections

This approach works best for CI/CD pipelines and local development environments where you want to switch directories without modifying configuration files.

JSON Configuration File

Add the property directly to your Deploy CLI configuration file (typically config.json):

{
  "AUTH0_DOMAIN": "tenant.auth0.com",
  "AUTH0_CLIENT_ID": "abc123",
  "AUTH0_CLIENT_SECRET": "def456",
  "AUTH0_CONNECTIONS_DIRECTORY": "tenant-connections"
}

When using this method, the value is parsed during context initialization and passed to the directory handlers automatically.

Practical Examples

These examples demonstrate complete workflows for exporting and importing connection definitions using custom directory paths.

Exporting to a Custom Directory

Run the export command after setting your custom directory environment variable:

export AUTH0_CONNECTIONS_DIRECTORY=tenant-connections
npm run build && node lib/index.js export -c config.json -f directory -o ./exported

The resulting file structure will place connection JSON files in your specified folder rather than the default:

exported/
└─ tenant-connections/
   ├─ github.json
   └─ google-oauth2.json

Importing from a Custom Directory

To import connections from a non-standard location, specify the directory in your configuration file and run the import command:

// config.json
{
  "AUTH0_DOMAIN": "my-tenant.auth0.com",
  "AUTH0_CLIENT_ID": "abc123",
  "AUTH0_CLIENT_SECRET": "def456",
  "AUTH0_CONNECTIONS_DIRECTORY": "my-connections"
}

npm run build && node lib/index.js import -c config.json -i ./my-deploy-context

The CLI searches for my-deploy-context/my-connections/*.json instead of the default my-deploy-context/connections/*.json.

Directory Structure Requirements

When using a custom connection directory, maintain the same file naming conventions and JSON schema that the Deploy CLI expects for connection assets.

Place individual connection configuration files as JSON objects within your specified folder:

./my-deploy-context/
└─ custom-connections/
   ├─ github.json
   └─ google-oauth2.json

Each JSON file must contain valid Auth0 connection configuration properties. The CLI validates these against the Management API schema during import operations.

Summary

• The AUTH0_CONNECTIONS_DIRECTORY configuration property overrides the default connections folder path in auth0/auth0-deploy-cli.
• Source code in src/context/directory/handlers/connections.ts implements the lookup logic with fallback to src/tools/constants.ts.
• Define this value via environment variables for temporary overrides or JSON configuration for persistent project settings.
• The custom directory path is resolved relative to your deployment context root during both import and export operations.

Frequently Asked Questions

What happens if I don't set AUTH0_CONNECTIONS_DIRECTORY?

If you omit this configuration property, the Deploy CLI automatically defaults to a directory named connections located at the root of your context folder. This default is defined as CONNECTIONS_DIRECTORY in src/tools/constants.ts and applied in src/context/directory/handlers/connections.ts when the configuration value is falsy.

Can I use absolute paths with AUTH0_CONNECTIONS_DIRECTORY?

The Deploy CLI resolves the path relative to the context directory specified by the -i or -o command-line arguments. While you can attempt to use absolute paths, the implementation concatenates this value within the directory handler context, making relative paths the reliable choice for cross-platform compatibility.

Does this setting affect YAML format deployments?

No. The AUTH0_CONNECTIONS_DIRECTORY property specifically applies to directory format deployments (-f directory). When using YAML format (-f yaml), connections are stored within the single YAML file structure rather than separate JSON files in a dedicated folder, rendering this configuration property irrelevant for that format.

Can I change the directory for other entity types like rules or clients?

Yes. The Auth0 Deploy CLI provides similar configuration properties for other asset types, following the same naming pattern: AUTH0_RULES_DIRECTORY, AUTH0_CLIENTS_DIRECTORY, AUTH0_RESOURCE_SERVERS_DIRECTORY, and others. Each follows the same fallback logic to constants defined in src/tools/constants.ts.

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