# How to Specify Connection Directories for Deployment Using AUTH0_CONNECTIONS_DIRECTORY

> Specify connection directories for Auth0 deployment with AUTH0_CONNECTIONS_DIRECTORY. Override default paths for import export operations to streamline your workflow.

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

---

**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`](https://github.com/auth0/auth0-deploy-cli/blob/main/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:

```typescript
// 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`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/tools/constants.ts) (line 106), which is hardcoded as `'connections'`.

The configuration interface in [`src/types.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/types.ts) (line 79) declares this property as optional:

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

```bash
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`](https://github.com/auth0/auth0-deploy-cli/blob/main/config.json)):

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

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

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

```

```bash
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`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/directory/handlers/connections.ts) implements the lookup logic with fallback to [`src/tools/constants.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/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`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/tools/constants.ts) and applied in [`src/context/directory/handlers/connections.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/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`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/tools/constants.ts).