Managing Apps with the Dash Enterprise CLI

Dash Enterprise features a command line interface (CLI) that allows you to perform some app management actions from the command line.

The CLI commands that you can run, as well as the output of some commands, are determined by your roles and app ownership on Dash Enterprise. Your permissions correspond to the same as those applied when performing actions in the Dash Enterprise App Manager UI. To review the permissions that each role grants, go to Roles and Permissions.

The Dash Enterprise CLI notably simplifies app deployment, but also allows you to list, initialize, and update apps—among other actions—without opening the App Manager.

App deployment using the CLI is based on Git and is available regardless of how your administrator has configured authentication for Dash Enterprise. It uses HTTPS, so there is no need to set up SSH keys.

Prerequisites

Before you install the Dash Enterprise CLI, make sure you have the following:

Python:
- Supported: 3.6 - 3.12
- Recommended: 3.8 - 3.12
Git (required for app deployment)

In Dash Enterprise Workspaces, these prerequisites are already met.

Installing the CLI

The Dash Enterprise CLI is available with the de-client package, which is included in dash-enterprise-libraries.

To begin using the CLI from your workstation, install the latest version with:

pip install dash-enterprise-libraries --extra-index-url https://<your-dash-enterprise-server>/packages

This also installs the latest versions of the following Dash Enterprise libraries:

Snapshot Engine
Dash Design Kit
Dash Enterprise Auth
Dash Embedded
Dash Notes
Dash User Analytics

If you have Python 3.6 or 3.7, the latest version of the Dash Enterprise CLI (de-client) that you can install is v1.2.5. We recommend upgrading to Python 3.8 or higher to use more recent versions.

You can use the CLI from any directory in the environment that you install it in. Note that no new files are added to the directory in which you install it.

The Dash Enterprise CLI and the libraries above come preinstalled in Dash Enterprise Workspaces.

Updating the CLI

Plotly releases new versions of the CLI that add and improve functionalities. You don't need to wait for your administrator to upgrade Dash Enterprise in order to update the CLI.

Check your CLI version with:

de --version

The output is similar to:

de_client, version 1.8.0

Update the CLI by running:

pip install dash-enterprise-libraries --upgrade --upgrade-strategy eager --extra-index-url https://<your-dash-enterprise-server>/packages

--upgrade-strategy eager ensures that all dependencies of dash-enterprise-libraries are upgraded, including de-client.

If you have Python 3.6 or 3.7, the latest version of the Dash Enterprise CLI (de-client) that you can update to is v1.2.5. We recommend upgrading to Python 3.8 or higher to use more recent versions.

Getting Started

The entry point to the CLI is

de

The output is similar to

Usage: de [OPTIONS] COMMAND [ARGS]...

   ___          _      ___     _                    _
  |   \ __ _ __| |_   | __|_ _| |_ ___ _ _ _ __ _ _(_)___ ___
  | |) / _` (_-< ' \  | _|| ' \  _/ -_) '_| '_ \ '_| (_-</ -_)
  |___/\__,_/__/_||_| |___|_||_\__\___|_| | .__/_| |_/__/\___|
                                          |_|

  Get started by logging into your Dash Enterprise instance with:

  $ de --host <HOST> login

Options:
  --host TEXT     Required if logging in for the first time
  --keyfile TEXT  Default: ~/.dash_enterprise/credentials.json
  --no-keyfile    Use $DASH_ENTERPRISE_USERNAME and $DASH_ENTERPRISE_PASSWORD
                  for authentication. Only supports native Keycloak accounts.
  --version       Show the version and exit.
  --help          Show this message and exit.

Commands:
  apps      Commands related to app management on Dash Enterprise.
  deploy    Deploy an app at a given path.
  docs      Open docs in browser.
  login     Log in to Dash Enterprise
  logout    Log out from Dash Enterprise
  run       Start a Dash development server for a given app.
  services  Commands related to service management on Dash Enterprise.
  whoami    Get information on the current logged-in user

Authentication and Authorization

Running CLI commands calls the Dash Enterprise Platform API. The Dash Enterprise Platform API is protected, and you can only call it if you are authorized. The authorization server is Keycloak. Over OAuth/Open ID Connect (OIDC), the CLI requests access and offline tokens from Keycloak for authorization. The access token lifespan is defined by the access token and offline token settings that your administrator has configured in Keycloak. By default, access tokens are valid for 24 hours and refreshed for 30 days.

Logging Your Device into the CLI

There are two ways to log in to the CLI: via a browser-based flow, or by providing a username and password.

We recommend the username and password method for CI/CD workflows, and the browser-based flow otherwise. Note that the username and password method is only compatible with users who were created natively in Keycloak (not brokered from an identity provider).

Browser-based authentication

Authentication with username and password

This method requires OAuth2 Device Authorization Grant to be turned on for the dash client in the Keycloak admin console. This setting is turned on by default, but browser-based login will be unavailable if it is turned off.

The OAuth2 Device Authorization Grant setting is turned on in the dash client configuration of the Keycloak admin console

To log your device into the CLI using the browser-based authentication method:

de --host example.plotly.host login

replacing the example host name with your Dash Enterprise host name (without https).

This uses the token information in ~/.dash_enterprise/credentials.json or creates it if none exists.

If you need to specify a different credentials file, use

de --host example.plotly.host --keyfile <path-to-keyfile> login

where <path-to-keyfile> is the path to the credentials file you want to use, and replacing the example host name with your Dash Enterprise host name (without https).

Your browser opens to a page prompting you to grant access privileges (if it does not open automatically, use the provided URL). Select Yes to begin using the CLI.

The browser prompts for confirmation to grant access privileges

When you grant access privileges, you are logged in and a message similar to the following is printed.

Logged in as [jessica] to [example.plotly.host]!

Once logged in, you no longer need to specify your Dash Enterprise host name when using the CLI.

Checking the Logged In User

To check which user is currently logged in:

de whoami

The output is similar to

Logged in as [jessica] to [example.plotly.host].

Logging Out

To log out:

de logout

Or, if you logged in using a credentials file other than ~/.dash_enterprise/credentials.json:

de --keyfile <path-to-keyfile> logout

where <path-to-keyfile> is the path to the credentials file you used to log in.

Logging out clears the contents of the credentials.json file (but does not delete it) if you logged in using the browser-based flow.

App Management Commands

You must have a license seat to run the commands below.

Initializing Apps

To initialize an app on Dash Enterprise:

de apps create --name <app-name>

where <app-name> is the name you want to give to the app.

The output is similar to

App <app-name> was initialized on [example.plotly.host].

Deploying Apps

The instructions below assume that you are using the CLI on your workstation. While CLI-based deployment works in Workspaces, we recommend one-click deploy to deploy from a workspace because it's a single button click.

You can deploy an app to Dash Enterprise using the CLI even if the app is not initialized.

To deploy or redeploy an app:

de deploy <path> --name <app-name>

where <path> is the path to the app folder on your workstation and <app-name> is the name of the new or existing app (both are optional). If you don't provide a path, Dash Enterprise uses the current directory. If you don't provide an app name, Dash Enterprise uses the name of your app folder. Remember that the name is used in the app URL and cannot be changed later.

The behavior is as follows:

If the app isn't initialized (and the name is available), you are prompted to confirm that you want to initialize it. It is then initialized and deployed, and you become the app owner.
If the app is initialized and not deployed, and you are its owner or co-owner, you are prompted to confirm that you want to overwrite it, and it is deployed.
If the app is initialized and deployed, and you are its owner or co-owner, you are prompted to confirm that you want to overwrite it, and it is redeployed.
Tip: You can use the -y flag (de deploy -y) to automatically answer "Yes" to all prompts, which may be useful as part of a CI workflow.

All app deployments from the CLI are over HTTPS.

Internally, to deploy your app, the Dash Enterprise CLI creates a copy of your app folder in ~/AppData/Local/Temp, then runs git init, git add ., git commit, and git push -f in the temporary directory. This force pushes the files in your app folder such that if the app already exists on Dash Enterprise, it is fully overwritten to match your local app files. Any .gitignore files are respected. The temporary directory is then deleted.

Run de deploy --help for additional options.

Listing and Checking Apps

To list the apps on Dash Enterprise:

de apps list

A list of apps that you own and co-own is displayed. If you have the admin role, then all apps are listed, regardless of which ones you own.

To check whether an app with the specified name exists:

de apps exists --name <app-name>

where <app-name> is the name you want to check.

To check the build status of an app:

de apps status --name <app-name>

where <app-name> is the name of the app whose build status you want to check. You must be the app owner or a co-owner, or have the admin role, to obtain this information.

The output is queued, building, built, or failed. If the app has never been deployed, the output is This app has not been deployed and has no previous builds.

To check the build logs of an app's most recent build:

de apps logs --name <app-name> --type build

where <app-name> is the name of the app whose build logs you want to check. You must be the app owner or a co-owner, or have the admin role, to obtain this information.

Only the most recent build's logs are available. By default, the 200 most recent lines are displayed. To specify a different number of lines, use --count followed by the number of lines you want. For example, de apps logs --name my-app --type build --count 50.

To check an app's runtime logs:

de apps logs --name <app-name> --type runtime

where <app-name> is the name of the app whose runtime logs you want to check. You must be the app owner or a co-owner, or have the admin role, to obtain this information.

By default, the logs for the web process are displayed. To specify a different process, use --process-name followed by the process as specified in the app's Procfile. For example, de apps logs --name my-app --type runtime --process-name scheduler.

By default, the 200 most recent lines are displayed. To specify a different number of lines, use --count followed by the number of lines you want. For example, de apps logs --name my-app --type runtime --count 50.

Listing and Checking Services

To list the Redis databases on Dash Enterprise:

de services list --type redis

To list the Postgres databases on Dash Enterprise:

de services list --type postgres

To list all services (Redis and Postgres databases combined) on Dash Enterprise:

de services list --type all

A list of services attached to apps that you own and co-own is displayed. If you have the admin role, then all services of the specified type are listed, regardless of which apps you own.

To check whether a specific app has a Redis database attached:

de services exists --name <app-name> --type redis

where <app-name> is the name of the app.

To check whether a specific app has a Postgres database attached:

de services exists --name <app-name> --type postgres

where <app-name> is the name of the app.

The output is True when the app has the specified type of service attached and False when it does not.

Updating Apps

You must be the app owner or a co-owner, or have the admin role, to run the commands below.

Attaching Services

To attach a Redis database to an app:

de services create --app-name <app-name> --type redis

where <app-name> is the name of the app that you want to attach the service to.

To attach a Postgres database to an app:

de services create --app-name <app-name> --type postgres

where <app-name> is the name of the app that you want to attach the service to.

Adding, Updating, and Removing Environment Variables

To add an environment variable:

de apps update --name <app-name> --add-environment-variable <env-var>

where <app-name> is the name of the app that you want to edit and <env-var> is the key and value of the environment variable you want to add, in the format KEY=VALUE.

To update an environment variable:

de apps update --name <app-name> --add-environment-variable <env-var>

where <app-name> is the name of the app that you want to edit and <env-var> is the key and new value of the environment variable you want to update, in the format KEY=VALUE.

To remove an environment variable:

de apps update --name <app-name> --remove-environment-variable <env-var-key>

where <app-name> is the name of the app that you want to edit and <env-var-key> is the key of the environment variable you want to remove.

Enabling and Disabling the Persistent Filesystem

To enable the persistent filesystem:

de apps update --name <app-name> --persistent-filesystem

where <app-name> is the name of the app that you want to edit.

To disable the persistent filesystem:

de apps update --name <app-name> --no-persistent-filesystem

where <app-name> is the name of the app that you want to edit.

Changing the App Viewer Access Level

To change the viewer access level to Restricted:

de apps update --name <app-name> --view-access restricted

where <app-name> is the name of the app whose viewer access level you want to change.

To change the viewer access level to Authenticated:

de apps update --name <app-name> --view-access authenticated

where <app-name> is the name of the app whose viewer access level you want to change.

To change the viewer access level to Unauthenticated:

de apps update --name <app-name> --view-access unauthenticated

where <app-name> is the name of the app whose viewer access level you want to change.

For details on viewer access, see Viewer Access.

Adding and Removing Viewers

To add a single viewer:

de apps update --name <app-name> --add-viewer <username>

where <app-name> is the name of the app that you want to edit and <username> is the username of the user that you want to add as a viewer.

To add all the members of a group as viewers:

de apps update --name <app-name> --add-group-viewer <group-name>

where <app-name> is the name of the app that you want to edit and <group-name> is the name of the group whose members you want to add as viewers.

To remove a single viewer:

de apps update --name <app-name> --remove-viewer <username>

where <app-name> is the name of the app that you want to edit and <username> is the username of the user that you want to remove as a viewer.

To remove all the members of a group as viewers:

de apps update --name <app-name> --remove-group-viewer <group-name>

where <app-name> is the name of the app that you want to edit and <group-name> is the name of the group whose members you want to remove as viewers.

Adding and Removing Co-Owners

To add a single co-owner:

de apps update --name <app-name> --add-co-owner <username>

where <app-name> is the name of the app that you want to edit and <username> is the username of the user that you want to add as a co-owner. This user must have a license seat.

To add all the members of a group as co-owners:

de apps update --name <app-name> --add-group-co-owner <group-name>

where <app-name> is the name of the app that you want to edit and <group-name> is the name of the group whose members you want to add as co-owners. All group members must have license seats.

To remove a single co-owner:

de apps update --name <app-name> --remove-co-owner <username>

where <app-name> is the name of the app that you want to edit and <username> is the username of the user that you want to remove as a co-owner.

To remove all the members of a group as co-owners:

de apps update --name <app-name> --remove-group-co-owner <group-name>

where <app-name> is the name of the app that you want to edit and <group-name> is the name of the group whose members you want to remove as co-owners.

Changing the App Title

To change an app's title:

de apps update --name <app-name> --title <new-title>

where <app-name> is the name of the app that you want to edit and <new-title> is the title that you want to set. If the title contains spaces, be sure to use quotes (for example, --title "my title with spaces").

The current title, if any, is changed to the new title.

Changing the App Description

To change an app's description:

de apps update --name <app-name> --description <new-description>

where <app-name> is the name of the app that you want to edit and <new-description> is the description that you want to set.

The current description, if any, is changed to the new description.

Changing the App Visibility in the Portal

To make an app visible in the Portal:

de apps update --name <app-name> --visible-on-portal

where <app-name> is the name of the app whose portal visibility you want to change.

To make an app not visible in the Portal:

de apps update --name <app-name> --not-visible-on-portal

where <app-name> is the name of the app whose portal visibility you want to change.

Changing the Thumbnail

To change an app's thumbnail:

de apps update --name <app-name> --thumbnail <path-to-file>

where <app-name> is the name of the app that you want to edit and <path-to-file> is the path to the image file you want to set as the thumbnail (must be a PNG or JPEG file of 100 KB or less).

The current thumbnail, if any, is changed to the new thumbnail.

Changing the Portal Rank

To change an app's rank in the Portal:

de apps update --name <app-name> --portal-rank <rank>

where <app-name> is the name of the app that you want to edit and <rank> is the rank that you want to set (must be an integer).

Changing the Maintainer Email Address

To change the maintainer email for an app:

de apps update --name <app-name> --maintainer-email your_email@example.com

where <app-name> is the name of the app you want to edit, and replacing the example email address with the maintainer email address you want to set.

The current maintainer email address, if any, is changed to the new maintainer email address.

Adding and Removing Tags

To add a tag:

de apps update --name <app-name> --tag <tag-name>

where <app-name> is the name of the app you want to edit and <tag-name> is the name of the tag you want to add.

You can only add one tag at a time.

To remove a tag:

de apps update --name <app-name> --remove-tag <tag-name>

where <app-name> is the name of the app you want to edit and <tag-name> is the name of the tag you want to remove.

You can only remove one tag at a time.

Restarting Apps

New in version 1.8.0

The apps restart command restarts all of an app's processes and workspace (if any), as long as they are running. See Using Workspaces for details on what happens to your files when a workspace is restarted.

To restart an app's processes and workspace:

de apps restart --name <app-name>

where <app-name> is the app whose processes and workspace you want to restart.

The output is similar to

Restarting workspace for app <app-name>
Restarting web for app <app-name>
Restarting worker for app <app-name>

Deleting Apps

To delete an app:

de apps delete --name <app-name>

where <app-name> is the name of the app you want to delete.

Deleting Services

To delete a Redis database:

de services delete --app-name <app-name> --type redis

where <app-name> is the name of the app that the Redis database is attached to.

To delete a Postgres database:

de services delete --app-name <app-name> --type postgres

where <app-name> is the name of the app that the Postgres database is attached to.

Other Commands

Opening Dash and Dash Enterprise Documentation

To open Dash and Dash Enterprise documentation:

de docs

Your browser opens to https://<your-dash-enterprise-server>/docs (if it does not open automatically, use the provided URL). Note that if you don't have a license seat, this redirects to a "Forbidden" page. You can still view Dash Open Source documentation (as well as information about some Dash Enterprise capabilities) without a license seat by going to https://dash.plotly.com/.

Rate Limit

In order to ensure high uptime, Dash Enterprise imposes a limit on the number of actions you can perform in a given time frame. This rate limit is specific to each user and is applied both to actions performed via the CLI and those performed through the App Manager.

The rate limit assigns points to each action and you consume these points when interacting with Dash Enterprise. Actions that create, modify, or delete resources on Dash Enterprise consume more points than actions like listing resources. When you have no remaining points, the limit is exceeded and an error similar to the following is displayed.

{
  "error": {
    "errors": [
      {
        "message": "Rate limit exceeded",
        "stacktrace": {
          "remainingPoints": 0,
          "msBeforeNext": 9669,
          "consumedPoints": 59,
          "isFirstInDuration": false
        },
        "extensions": {
          "code": "TOO_MANY_REQUESTS"
        }
      }
    ]
  }
}

You'll need to wait 60 seconds before you can continue.

If using the CLI as part of a CI/CD pipeline, follow these recommendations to avoid being disrupted by the rate limit:

Throttle the requests that your pipeline makes to Dash Enterprise
Make sure your code doesn't create infinite loops
Handle errors

Limitations and Known Issues

Not all actions available in the App Manager UI have corresponding CLI commands.
It is not possible to initialize an app from the App Catalog using the CLI.
Apps initialized with the CLI are given a title corresponding to the name that you set. You can remove the title in the Settings tab of the App Info.
Attempting to exit after beginning the browser-based login doesn't always correctly abort. You may need to try again or close the terminal.
Special characters in DASH_ENTERPRISE_USERNAME and DASH_ENTERPRISE_PASSWORD are not URL encoded, which causes CLI commands to fail. As a workaround, you can manually URL encode special characters (for example, replace @ with %40).
During app deployment, the CLI creates a temporary directory for the Git repository. On Windows computers, this directory is not removed after the deployment succeeds.
If you receive the error certificate verify failed: unable to get local issuer certificate, this means that when configuring Dash Enterprise, your administrator has used a TLS/SSL full chain certificate whose root certificate was issued by an internal certificate authority (CA). Ask your administrator for the root certificate file, then do the following:
- Update the CLI to v1.9.0 or later if it isn't already.
- Add --ca-path <path-to-root-ca> to your commands. For example, to deploy an app from your workstation, use de --ca-path <path-to-root-ca> deploy <path> --name <app-name>, where <path-to-root-ca> is the path to the root certificate file. Alternatively, you can set the environment variable DASH_ENTERPRISE_CA_PATH to this path.