Command Line Interface

The Descope Command Line Interface (CLI) helps manage your Descope project by leveraging its management APIs. It enables handling tasks like creating users, managing tenants, generating access keys, and modifying project settings through the command line.

With support for exporting, validating, and importing snapshots, the CLI simplifies project configuration and transfer. Its ability to output JSON makes it ideal for automation in scripts and CI/CD workflows, saving time and reducing errors. To see more about our CI/CD check out our Github CI/CD guide and Github CI/CD Template.

Prerequisites

The repository for the Descope CLI can be found here.

Install the CLI tool according to your device, instructions can be found in the repository.
You will need the Project ID for the project you want to manage, this can be found in Project Settings
You will also need to generate a management key within Company Settings.

To set your Project ID and Management Key for the CLI, use the commands below. If you want to update them permanently add them to your terminal profile, such as .zshrc or .bashrc.

export DESCOPE_PROJECT_ID='<Your_Project_ID>' 
export DESCOPE_MANAGEMENT_KEY='<Your_Management_Key>'

Note

If you need help on any command or sub-command you can put the -h flag at the end of the full command to get more information and flags.

Creating and Managing Project Entities

With the CLI you can create and manage different Descope Entities. Entities are Users, Access Keys, and Tenants.

Access-Keys

These are the available commands for creating and managing access keys:

  activate	      Activate an access key
  create          Create a new access key
  deactivate   	  Deactivate an access key
  delete     	  Delete an access key
  load            Load details about an access key
  load-all        Load all access keys

When creating an access key there are several attributes you can pass in. You can get these attributes with the -h flag:

descope access-key create -h

All the information about the command is returned:

Usage:
  descope access-key create <name> [-d description] [-e time] [-t tenants] [-u userId]

Flags:
  -d, --description string   an optional description for the access key
  -e, --expires int          the access key's expiry time (unix time in seconds, default 0 to not expire)
  -t, --tenants strings      a comma separated list of tenant ids for the access key
  -u, --userId string        an optional user id to adopt authorizations from
  -j, --json                 use JSON output format

As an example say we wanted to create an access key that expires Nov 21, 2026 which is 1795345322 Unix Time, is associated with a tenant, and takes all the project and tenant level roles and permissions of one of our users:

descope access-key create exampleKey -e 1795345322 -u 'U2piAnrm6sV1OKyGTUejqddWVSai' -t 'acmecorp' -j

The access key is returned, it is in the cleartext field:

{
  "accessKey": {
    "boundUserId": "U2piAnrm6sV1OKyGTUejqddWVSai",
    "cleartext": "K2pjAnGVR7ez6pVqSI9mCul88IppLc0FpV9WQVnDBwRARNr5BaU56hnN61Gvm5LoWD2YW7S",
    "clientId": "UDJsTm50UzhRcDdVOTVOaXVyWUZRaEsxbkRUUjpLMnBqQW5HVlI3ZXo2cFZxU0k5bUN1bDg4SXBw",
    "createdBy": "K2pB49mv9n7WCVbbcC7KKkXM5jo4",
    "createdTime": 1733269275,
    "expireTime": 1795345322,
    "id": "K2pjAnGVR7ez6pVqSI9mCul88Ipp",
    "keyTenants": [
      {
        "tenantId": "acmecorp",
        "tenantName": "AcmeCorp"
      }
    ],
    "name": "exampleKey",
    "status": "active"
  },
  "ok": true
}

You can see your newly created access key in the Access Key tab.

Tenants

These are the available commands for creating and managing tenants:

  create      Create a new tenant
  delete      Delete a tenant
  load        Load details about a tenant
  load-all    Load all tenants

When creating a Tenant we can pass the following flags:

Usage:
  descope tenant create <name>
 
Flags:
  -i, --id string         an optional custom id for the tenant
  -d, --domains strings   a comma separated list of self provisioning domains for the tenant
  -j, --json              use JSON output format

As an example let's create a tenant with self provisioning domains and a custom tenant id:

descope tenant create 'TestTenant'  -i 'testtenant' -d 'example.com','example.org' -j

To load the tenant we just created we can use the load command:

descope tenant load ‘testtenant’ -j

We can see the name, self-provisioning domains, authentication methods, and created time:

{
  "ok": true,
  "tenant": {
    "id": "testtenant",
    "name": "TestTenant",
    "selfProvisioningDomains": [
      "example.com",
      "example.org"
    ],
    "authType": "none",
    "createdTime": 1733339035
  }
}

We can see our tenant and its settings in the Tenants Page.

Users

These are the available commands for managing and creating users and test users:

  activate    Activate a user
  create      Create a new user
  deactivate  Deactivate a user
  delete      Delete a user
  load        Load details about a user
  load-all    Load all users
  password    Commands for managing user passwords
  roles       Commands for managing user roles
  test        Commands for creating and managing test users

The following flags are available for user creation:

Usage:
  descope user create <loginId> [-e email] [-p phone] [-n name] [-t tid,...]

Flags:
  -e, --email string      the user's email address
  -p, --phone string      the user's phone number
  -n, --name string       the user's display name
  -t, --tenants strings   a comma separated list of tenant ids for the user
  -j, --json              use JSON output format

As an example let's say we wanted to create a user associated with tenants, we can do the following:

descope user create 'john@example.com' -p '+11234567890' -t 'acmecorp','testtenant' -j

They will be set as invited in the descope console:

Their status can be manually changed from Invited to Active using the activate sub-command.

descope user activate 'john@example.com' -j

Now if we load the user we can see their status is set to enabled:

descope user load -l 'john@example.com' -j

{
  "ok": true,
  "user": {
    "phone": "+11234567890",
    "userId": "U2poJTufi0fAPgCEySTao5qmtk6j",
    "loginIds": [
      "john@example.com"
    ],
    "verifiedPhone": true,
    "userTenants": [
      {
        "tenantId": "acmecorp",
        "tenantName": "AcmeCorp"
      },
      {
        "tenantId": "testtenant",
        "tenantName": "TestTenant"
      }
    ],
    "status": "enabled",
    "createdTime": 1733426505
  }
}

User Roles

We can manage a user’s roles through the roles sub-command. These are the available commands for roles:

  add         Add roles to a user
  remove      Remove roles from a user
  set         Set the roles for a user

Note

Adding a role will append to current roles. Setting roles will overwrite any existing roles.

Here is an example of adding a tenant-level role to a user:

descope user roles add john@example.com -t 'acmecorp' -r 'Tenant Admin','acmeRole' -j

If we wanted to add project-level roles we can run the command again with no input for tenant.

User Passwords

We can set active and temporary passwords for a user as well as expire their existing password using the password sub-command:

  expire         Expire a user's password
  set-active     Set an active password for a user
  set-temporary  Set a temporary password for a user

We can set a temporary password which will require a user to change their password on the next authentication:

descope user password set-temporary 'michael.rimboim@descope.com' 'a8&#32re7f9E' -j

This can be accomplished by having a replace password section of the flow like below, the user will be able to use this temporary password to create a new one:

Test Users

Using the CLI we can programmatically create test users and generate logins for these users with the test sub-command:

  create      Create a new test user
  delete-all  Delete all existing test users in the project
  generate    Commands for generating logins for test users

Creating a test user works the same as creating a regular user:

 descope user test create test@descope.com -p "+19999999999" -j

You can generate a test verification code for a test user. Let's create a SMS OTP we can use and reuse for this test user:

descope user test generate otp sms test@descope.com

We get back the OTP code we can use in place of a real OTP code during verification.

Managing the Project

The descope CLI allows you to manage flows, audits, projects, and themes

Audit

You can use the audit search command to do a fuzzy search of audit logs from the past 30 days:

Here is an example of searching for all audit logs that include the word Mozilla:

descope audit search “Mozilla” -j

To store logs longer than 30 days you must stream them to your own service, see here

Flow

Using the CLI we can programmatically import and export flows:

  convert     Convert a flow between formats
  export      Export a flow to a JSON file or standard output
  import      Import a flow from a JSON file
  list        Lists all flows in a project

Here is an example of exporting a flow to a JSON file:

descope flow export "sign-up-or-in" > sign-up-or-in.json

Project

Using the CLI you can manage the creation of project snapshots and validation. These are the available base commands:

  clone       Clone an existing project along with all settings and configurations
  delete      Delete an existing project
  list        Lists all projects in a company
  snapshot    Commands for working with project snapshots

The snapshot subcommand allows you to import and export projects. These commands are useful for CI/CD automation.

  export      Export a snapshot of all the settings and configurations of a project
  import      Import a snapshot into a project
  validate    Validate a snapshot before importing into a project

Note

To learn more about project import/export and how to handle project secrets properly see here

Theme

Using the CLI tool you can manage the export and import of the project theme. These are the available commands:

  export      Export the project theme to a JSON file or standard output
  import      Import the project theme from a JSON file

Exporting the theme gives a JSON file with all the styles that exist in a project.

descope theme export testTheme.json

Was this helpful?

On this page