Auth0 CLI Basics

In this lab, you will:

• Build, manage, and test your Auth0 integrations from the command line.
• Test your Auth0 Universal Login flow.
• Troubleshoot in real-time.
• Simplify repetitive tasks.

What is the Auth0 CLI?

For developers unfamiliar with the Auth0 CLI, it is a powerful tool designed to streamline and enhance your Auth0 development experience. When integrating an application with Auth0, you may have found yourself juggling the Auth0 Dashboard, the Auth0 docs, your code editor, and your terminal application. The Auth0 CLI simplifies the way you interact with Auth0 and enables you to get complete tasks in less time. The Auth0 CLI empowers you to manage your Auth0 tenants effortlessly from the command line and automate tasks such as creating users, assigning roles, updating applications, and accessing unique features tailored to streamline your Auth0 integration process.

The latest version comes with new features and improvements to streamline your Auth0 development experience and boost efficiency. Let's explore the basics to get you started!

Lab Setup

Required hardware

To complete this lab, you need a computer running macOS, Windows, or Linux.

Create an Auth0 Account

If you already have an Auth0 account, you can log in to your tenant and continue to the next step.

Otherwise, sign up for a free Auth0 account.

During the sign-up process, you create something called an Auth0 Tenant, representing the product or service to which you are adding authentication.

Install the Auth0 CLI

There are different ways to install the Auth0 CLI, depending on your operating system.

macOS

You can install the Auth0 CLI using Homebrew, package manager for macOS:

brew tap auth0/auth0-cli && brew install auth0

Windows

You can install the Auth0 CLI using Scoop, a command-line installer for Windows.

First, add the bucket:

scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git

Then, install the application:

scoop install auth0

Linux

You can install the Auth0 CLI using cURL, a command line tool and library for transferring data with URLs.

Download the binary to ./auth0:

curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh | sh -s -- -b .

If you want to run the binary from any directory, move the installation to a place in your $PATH. For example:

sudo mv ./auth0 /usr/local/bin

Go

You can install the Auth0 CLI using Go, an open-source programming language supported by Google:

go install github.com/auth0/auth0-cli/cmd/auth0@latest

Make sure that you export your $GOPATH/bin on your $PATH to run the binary from any directory.

Manual installation

You can install the Auth0 CLI manually by following these steps:

1. Download the appropriate binary for your environment from the latest release.
2. Extract the archive:

tar -xf auth0-cli_{version}_Darwin_{architecture}.tar.gz

3. Run the Auth0 CLI:

./auth0

4. Run the following command to get instructions on how to enable CLI autocompletion for your platform:

auth0 completion -h

Test the Auth0 CLI installation

Run the following command to show in the terminal the version of your Auth0 CLI installation:

auth0 --version

You should see the following output:

auth0 version <version-number> <hash>

Access Your Tenant

If you have been using Auth0 for a while, you may have one or more existing tenants. If you just signed up for Auth0 while following this lab, you created a tenant earlier.

You need to authorize the Auth0 CLI application to access your Auth0 tenant to use most CLI features and functionality. You can do so by "authenticating to your tenant" from the CLI, which means that you'll log in to the Auth0 platform, select the tenant that you want to use with the Auth0 CLI, and authorize the CLI to perform a set of actions on your behalf for that tenant.

Log in to your tenant

Start that process by running the following command:

auth0 login

The terminal then shows an output that is similar to the following:

✪ Welcome to the Auth0 CLI 🎊

An Auth0 tenant is required to operate this CLI.
To create one, visit: https://auth0.com/signup.

You may authenticate to your tenant either as a user with personal
credentials or as a machine via client credentials. For more
information about authenticating the CLI to your tenant, visit
the docs: https://auth0.github.io/auth0-cli/auth0_login.html

 How would you like to authenticate?  
    [Use arrows to move, type to filter, ? for more help]
> As a user
  As a machine

Select the option to authenticate As a user and press the <Enter> key on your keyboard.

You'll then see the following output:

Verify HDPJ-PQFM code in opened browser window to complete authentication.

 ▸    Press Enter to open the browser to log in or ^C to quit...

Once again, press the <Enter> key on your keyboard to open a browser window to carry out the tenant authentication process.

Verify that a browser window loads with the auth0.auth0.com/... domain. The page should display a "Device Confirmation" box that asks you to confirm that the code in the box matches the code in your terminal. If that's the case, click the "Confirm" button. Otherwise, click the "Cancel" button.

Next, an "Authorize App" box shows up, informing you that the Auth0 CLI application is requesting access to your Auth0 account. The "Authorize App" box has a drop-down field that lists the different Auth0 tenants that you may have by region.

Select the tenant that you'd like to access using the Auth0 CLI.

Recall that the Auth0 CLI allows you to build, manage and test your Auth0 integrations from the command line. As such, the Auth0 CLI requires a number of permissions to perform actions on your behalf for the selected tenant in the Auth0 platform. Those permissions are listed right below the drop-down field. Read them carefully and then click the "Accept" button.

A success message shows up on the browser, while the terminal where you started the login process should show the following output:

▸    Successfully logged in.
▸    Tenant: AUTH0-DOMAIN

The Tenant value is equivalent to your "Auth0 Domain", a critical value to connect your applications with Auth0.

As such, enter the Tenant value in the following field:

When you enter a value in the input fields present in this lab, any code snippet or command that uses such value updates to reflect it. Using the input fields makes it easy to copy and paste code as you follow along.

Register an Application

To connect a client application with Auth0, you need to create an API registration in the Auth0 Dashboard and get configuration values like the Auth0 Domain and the Auth0 Client ID.

You can easily create these application registrations using the Auth0 CLI by running the following command:

auth0 apps create

The Auth0 CLI will now prompt you to enter data about the client application you want to register.

Start by entering the application name, such as Hello Auth0:

$ auth0 apps create
 Name: [? for help]

Next, enter the application description, such as Exploring Auth0 features using the terminal

$ auth0 apps create
 Name: Hello World
 Description: [? for help]

Now, specify the type of client application that you are registering. For this lab, you'll focus on setting up and trying out the authentication flow of a Single Page Web Application:

$ auth0 apps create
 Name: Hello World
 Description: Exploring Auth0 features using the terminal
 Type:  [Use arrows to move, type to filter, ? for more help]
  Native
> Single Page Web Application
  Regular Web Application
  Machine to Machine

The following steps involve defining some properties that allow your client application to communicate with the Auth0 platform. Press <Enter> for each of the following values to accept their default value, http://localhost:3000:

• Callback URLs: The URL that Auth0 can use to redirect your users after they successfully log in.
• Allowed Logout URLs: The URL that Auth0 can use to redirect your users after they log out.
• Allowed Origin URLs: Additional origins allowed to make cross-origin resource sharing (CORS) requests.
• Allowed Web Origin URLs: Comma-separated list of allowed origins for use with Cross-Origin Authentication.

Upon success, the Auth0 CLI shows you the configuration information of your application registration:

Name: Hello World
Description: Exploring Auth0 features using the terminal
Type: Single Page Web Application
Callback URLs: http://localhost:3000
Allowed Logout URLs: http://localhost:3000
Allowed Origin URLs: http://localhost:3000
Allowed Web Origin URLs: http://localhost:3000

=== AUTH0-DOMAIN application created

CLIENT ID            AUTH0-CLIENT-ID           
NAME                 Hello World                                  
DESCRIPTION          Exploring Auth0 features using the terminal            
TYPE                 Single Page Web Application                  
CALLBACKS            http://localhost:3000                        
ALLOWED LOGOUT URLS  http://localhost:3000                        
ALLOWED ORIGINS      http://localhost:3000                        
ALLOWED WEB ORIGINS  http://localhost:3000                        
TOKEN ENDPOINT AUTH  none                                         
GRANTS               implicit, authorization_code, refresh_token

 ▸    Quickstarts: https://auth0.com/docs/quickstart/spa
 ▸    Hint: Emulate this app's login flow by running 
        `auth0 test login AUTH0-CLIENT-ID`
 ▸    Hint: Consider running 
        `auth0 quickstarts download AUTH0-CLIENT-ID`

Enter the Auth0 Client ID value in the following field:

The Auth0 CLI can use the Auth0 Client ID value to test the user login flow of a specific application registration. However, you first need a user that can log in!

Create a User

What's an essential component of a user login transaction? The user! The Auth0 CLI lets you create users to test different Auth0 features right from the terminal.

Run the following command to start the user creation flow:

auth0 users create

The first step in creating a user is to create the "Connection" for that user:

$ auth0 users create

 Connection Name:  [Use arrows to move, type to filter, ? for more help]
> Username-Password-Authentication

The default connection for every new tenant is the Username-Password-Authentication connection. Choose that option for the connection and press <Enter>.

Next, specify the user "Name", such as Dev:

$ auth0 users create
 Connection: Username-Password-Authentication
 Name: [? for help]

Now, enter an email address for the user:

You can enter a working email address to experience the email verification step. Otherwise, enter a value like dev@example.com for testing.

$ auth0 users create
 Connection: Username-Password-Authentication
 Name: Dev
 Email: [? for help]

Create a password for the new user:

$ auth0 users create
 Connection: Username-Password-Authentication
 Name: Dev
 Email: dev@example.com
 Password:

Enter a strong password at least 16 characters long, containing numbers, letters, and special characters.

The Auth0 CLI now shows you a confirmation message that includes the ID of the user that you just created, along with their email address and the Auth0 connection:

=== AUTH0-DOMAIN user created

ID          <random-string>    
EMAIL       dev@example.com                   
CONNECTION  Username-Password-Authentication

You can use the user ID with the Auth0 CLI to perform different transactions on users, such as showing, updating, or even deleting a user.

Try the following Auth0 CLI challenges

• Use the following command to display the user information:

auth0 users show

• Use the following command to update the user's name to Developer:

auth0 users update

• Use the following command to verify that the user's name has been updated:

auth0 users open

Test User Login

In this section, you'll use the Auth0 CLI to test the user login experience of the application you registered earlier. You'll need your Auth0 Client ID.

auth0 apps list

$ auth0 apps list

=== AUTH0-DOMAIN applications (<number-of-apps>)

  CLIENT ID                 NAME         TYPE                         
  <CLIENT-ID-1>             Default App  Generic                      
  <CLIENT-ID-2>             Hello World  Single Page Web Application

Run the following command to test logging into your application using the Auth0 Universal Login page:

auth0 test login AUTH0-CLIENT-ID

You'll see a list of expectations and implications of testing user login with the Auth0 CLI, along with a prompt to proceed:

▸    A browser window needs to be opened to complete this client's login flow.
▸    Once login is complete, you can return to the CLI to view user profile 
    information and tokens.
▸    The client you are using does not currently allow callbacks to localhost.
▸    To complete the login flow the CLI needs to redirect logins 
    to a local server and record the result.
▸    The client will be modified to update the allowed callback URLs, 
    we'll remove them when done.
▸    If you do not wish to modify the client, you can abort now.

Do you wish to proceed? (y/N)

Type y and press <Enter> to proceed.

A browser window opens up, presenting you with a login box.

When using the Auth0 Identity Platform, you don't have to build login forms. Auth0 offers a Universal Login Page to reduce the overhead of adding and managing authentication.

Log in with the username and password of the user that you created earlier.

Back to the terminal, you'll see the following information that comes from the /userinfo Auth0 endpoint:

{
  "user_info": {
    "sub": "...",
    "name": "...",
    "given_name": "...",
    "family_name": "...",
    "nickname": "...",
    "picture": "...",
    "locale": "...",
    "updated_at": "..."
  },
  "tokens": {
    "access_token": "...",
    "id_token": "...",
    "token_type": "Bearer",
    "expires_in": 86400
  }
}

You can customize the look and feel of the Auth0 Universal Login to match your brand guidelines. You can also enable social connections in your tenant to allow users to log in to your application using their profiles from another identity provider.

Display Tenant Logs

You can use the Auth0 CLI to view your tenant logs, which can help you find or troubleshoot issues when integrating Auth0 with your applications.

You can supercharge your development flow by displaying a tail log on the terminal, which is a log that displays recent data. As you take actions that affect your tenant, the tail log shows the effects of each action in real-time.

Open a new terminal window and run the following command to tail your tenant logs:

auth0 logs tail

Keep this terminal window open to observe the success or failure of the actions that you'll perform on your Auth0 tenant as you continue with this lab.

Let's trigger an error to see the tail logs in action. Start creating a user but enter a weak password, for example, 1234.

The Auth0 CLI should show you an error like the following:

 Connection: Username-Password-Authentication
 Name: Tek
 Email: tek@example.com
 Password: ***

=== AUTH0-DOMAIN error

 ▸    Unable to create user: 400 Bad Request: 
      PasswordStrengthError: Password is too weak

The Auth0 CLI displays an error that notifies you that it could not create a user on your behalf as the password is too weak. The Auth0 Authentication API rejected this user creation flow with a 400 (Bad Request) error.

Now, check out the terminal window that is tailing the logs.

You should see the following entry:

=== AUTH0-DOMAIN logs
Failed Signup              Password is too weak

Your tenant logs are the first place that you should inspect whenever you experience errors with your Auth0 applications or APIs. Operation errors will have helpful descriptions that provide context on what went wrong and how to make it right.

Try the following Auth0 CLI challenges

• Log in to your application again using the Auth0 Universal Login page and observe the events triggered by that transaction.
• Create a new user with the email tek@example.com and observe the tail logs. Was the operation error-free? If not, what do you think caused an error and why?

Log Out From Your Tenant

Finally, you can run the following command whenever you want to log out from the Auth0 CLI:

auth0 logout

The logout process affects a single tenant to which you have authenticated. As such, the Auth0 CLI will show you a tenant list from which you can log out. Upon success, you'll see a message like the following on your terminal:

Tenant: AUTH0-DOMAIN
▸    Successfully logged out tenant: AUTH0-DOMAIN

Recap

The Auth0 CLI marks a new chapter in the Auth0 development experience. With its enhanced feature set and stability, it can become a useful tool in your Auth0 toolkit. We invite you to try it out and share your feedback to help us make the Auth0 CLI even better.

Be sure to visit the Auth0 CLI GitHub repository to stay informed on the latest developments and join the growing community of Auth0 CLI users.

Get started with Auth0

// Install the Auth0 CLI: a0.to/get-cli

$ auth0 login

>
Press Enter to open the browser to log in

$ auth0 apps create

$ auth0 test login

> Select the app that you created

// Learn more: a0.to/learn-cli

View on GitHub

Report an issue

Give us feedback