Skip to main content

Before you start

Set up an Auth0 Tenant.
The Auth0 Deploy CLI is a tool that helps you manage your Auth0 tenant configuration. It integrates into your development workflows as a standalone CLI or as a node module. Supported resource types: actions, branding, client grants, clients (applications), connections, custom domains, email templates, emails, grants, guardian, hook secrets, log streams, migrations, organizations, pages, prompts, resource servers (APIs), roles, tenant settings, themes. Because client grants and resource servers (APIs) are supported resource types, the Deploy CLI can synchronize API permissions (scopes defined on your APIs) and the client grants that authorize applications to access those APIs across tenants. When you export from one tenant and import into another, the resource servers (APIs) resource carries the API definitions and their scopes, while the client grants resource carries which applications are granted access to which APIs and at what scopes. This means you can apply the same access levels your Dev-tenant applications have to your Staging tenant.
Client grants reference applications and APIs by identifier: client name for applications and audience for APIs. The corresponding clients (applications) and resource servers (APIs) must also exist (or be created) in the target tenant for the grants to resolve correctly.

​
Highlights

  • Multi-Environment Oriented: Designed to help you test your applications’ Auth0 integrations from feature branch all the way to production.
  • Keyword Replacement: Shared resource configurations across all environments with dynamic keyword replacement.
  • Versatile: Integrate into your CI/CD workflows either as a CLI or as a Node module.

​
Get started

This guide will help you to a working implementation of the Deploy CLI tool used as a standalone CLI. There are three main steps before the Deploy CLI can be run:
  1. Create a dedicated Auth0 Application
  2. Configure the Deploy CLI
  3. Call the Deploy CLI
This tool can be destructive to your Auth0 tenant. It is recommended to be familiar with the AUTH0_ALLOW_DELETE configuration and to test on development tenants prior to using in production.

​
Install the Deploy CLI

To run as a standalone command-line tool: npm install -g auth0-deploy-cli

​
Create a dedicated Auth0 application

In order for the Deploy CLI to call the , a dedicated Auth0 application must be created to make calls on behalf of the tool:
  1. Go to Auth0 Dashboard > Applications > Applications.
  2. Select + Create Application.
    1. Give it a descriptive name (such as “Deploy CLI”).
    2. Select Machine to Machine Applications for the Application Type.
    3. Select Create.
  3. Switch to the Authorize Machine to Machine Application view:
    1. Select Auth0 Management API.
    2. Select the appropriate permissions for the resources you wish to manage. Refer to the Client Scopes section for more information.
    3. Select Authorize.
The Deploy CLI’s own client is not configurable by itself to prevent potentially destructive changes.

​
Client scopes

The designated application needs to be granted scopes in order to allow the Deploy CLI to execute Management operations. The principle of least privilege is abided, so it will operate within the set of permissions granted. , you’ll need to select read:clients, but it’s recommended to select read:*, create:*, and update:* permissions for all resource types within management purview. To enable deletions, you delete:* scopes.

​
Configure the Deploy CLI

You can configure the Deploy CLI in two ways:
  1. Use the configuration file (config.json).
  2. Set environment variables.
The decision to choose one or both would depend on your specific use case and preferences. To learn more, read Configure the Deploy CLI. For this example, set the following environment variables:
  • AUTH0_DOMAIN
  • AUTH0_CLIENT_ID
  • AUTH0_CLIENT_SECRET
These values can be found in the Settings tab for the dedicated Auth0 application you created previously.

​
Call the Deploy CLI

The Deploy CLI export command can be run with the following command: a0deploy export --format=yaml --output_folder=local Once the process completes, observe the resource configuration files generated in the local directory. Then, run the import command to push the configuration from your local machine to your Auth0 tenant: a0deploy import --config_file=config.json --input_file local/tenant.yaml For a comprehensive list of flags and options, please read Use as CLI.