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 <a href="https://&lt;your-dash-enterprise-server&gt;/packages">https://&lt;your-dash-enterprise-server&gt;/packages</a>

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 <a href="https://&lt;your-dash-enterprise-server&gt;/packages">https://&lt;your-dash-enterprise-server&gt;/packages</a>

--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 Dash Enterprise. You'll need the hostname of
  your instance, which is the URL that you go to in your browser to access
  Dash Enterprise minus 'https,' like dash.example.com.

  To log in:

  $ de --host &lt;HOSTNAME&gt; login

Options:
  --host TEXT     Required if logging in for the first time
  --keyfile TEXT  Default: ~/.dash_enterprise/credentials.json
  --token TEXT    Encrypted keycloak token
  --no-keyfile    Use $DASH_ENTERPRISE_USERNAME and $DASH_ENTERPRISE_PASSWORD
                  for authentication. Only supports native Keycloak accounts.
  --ca-path TEXT  Path on disk to the root certificate for the signing
                  authority, if your DE instance uses internally-signed
                  certificates. This may be a `.pem` file. Alternatively, set
                  the $DASH_ENTERPRISE_CA_PATH environment variable.
  --version       Show the version and exit.
  -h, --help      Show this message and exit.

Commands:
  apps          Commands related to app management.
  data-sources  Commands related to data source management.
  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.
  whoami        Get information on the current logged-in user.
  workspaces    Commands related to workspace management.

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).

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 &lt;path-to-keyfile&gt; logout

where &lt;path-to-keyfile&gt; 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

Initializing Apps

To initialize an app on Dash Enterprise:

de apps create --name &lt;app-name&gt;

where &lt;app-name&gt; is the name you want to give to the app.

The output is similar to

App &lt;app-name&gt; 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 &lt;path&gt; --name &lt;app-name&gt;

where &lt;path&gt; is the path to the app folder on your workstation and &lt;app-name&gt; 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

App Existence

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 the existence of an app by name:

de apps exists --name &lt;app-name&gt;

where &lt;app-name&gt; is the name that you want to look up.

App Status

To check an app’s status as well as general information (new in version 1.10.0):

de apps info --name &lt;app-name&gt;

where &lt;app-name&gt; is the name of the app that you want to check.

To check the build status of a deployed app:

de apps status --name &lt;app-name&gt;

where &lt;app-name&gt; 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.

App Logs

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

de apps logs --name &lt;app-name&gt; --type build

where &lt;app-name&gt; 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 &lt;app-name&gt; --type runtime

where &lt;app-name&gt; 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.

App Access

New in version 1.10.0

To check which users have access to an app:

de apps users --name &lt;app-name&gt;

where &lt;app-name&gt; is the name of the app that you want to check.

Three lists are printed: owner, co-owners, and viewers.

Known issue: A list of viewers is printed for apps that are Unauthenticated or Authenticated. The actual users who can view the app extend beyond this list (all users for Unauthenticated apps and all logged in users for Authenticated apps).

Known issue: The app owner appears in the co-owners and viewers lists.

Transferring Apps

New in version 1.10.0

You must have the admin role to transfer apps.

To transfer one app from a licensed user to another:

de apps transfer --name &lt;app-name&gt; --from-user &lt;current-owner&gt; --to-user &lt;new-owner&gt;

where &lt;app-name&gt; is the name of the app that you want to transfer, &lt;current-owner&gt; is the app’s current owner, and &lt;new-owner&gt; is the user that you want to transfer the app to.

To transfer all of a licensed user’s apps to another:

de apps transfer-all --from-user &lt;current-owner&gt; --to-user &lt;new-owner&gt;

where &lt;current-owner&gt; is the user whose apps you want to transfer and &lt;new-owner&gt; is the user that you want to transfer them to.

Updating Apps

Unless otherwise noted, you must be the app owner or a co-owner, or have the admin role, to run the commands below.

Workspace Management Commands

New in version 1.10.0

To create a blank workspace (you must be the app owner):

de workspaces create --name &lt;app-name&gt;

where &lt;app-name&gt; is the name of the app that you want to create a workspace for.

The workspace is created with the default memory limit. To specify a custom memory limit (requires the admin role), add --memory-limit &lt;memory-limit&gt;, where &lt;memory-limit&gt; is the memory limit that you want to set in MiB (maximum 24576).

To create a workspace from a commit (you must be the app owner):

de workspaces create --name &lt;app-name&gt; --git-revision &lt;git-revision&gt;

where &lt;app-name&gt; is the name of the app that you want to create a workspace for and &lt;git-revision&gt; is the full Git revision to use.

The workspace is created with the default memory limit. To specify a custom memory limit (requires the admin role), add --memory-limit &lt;memory-limit&gt;, where &lt;memory-limit&gt; is the memory limit that you want to set in MiB (maximum 24576).

To view the status and general information about a workspace:

de workspaces info --name &lt;app-name&gt;

where &lt;app-name&gt; is the name of the app whose workspace you want to check.

To restart a workspace:

de workspaces update --name &lt;app-name&gt; --restart

where &lt;app-name&gt; is the name of the app whose workspace you want to restart. See the effects of restarting a workspace.

To rebuild a workspace (you must be the app owner or have the admin role):

de workspaces rebuild --name &lt;app-name&gt;

where &lt;app-name&gt; is the name of the app whose workspace you want to rebuild. See the effects of rebuilding a workspace.

To update a workspace’s memory limit (requires the admin role):

de workspaces update --name &lt;app-name&gt; --memory-limit &lt;new-limit&gt;

where &lt;app-name&gt; is the name of the app that the workspace belongs to and &lt;new-limit&gt; is the memory limit that you want to set in MiB (maximum 24576).

To delete a workspace (you must be the app owner or have the admin role):

de workspaces delete --name &lt;app-name&gt;

where &lt;app-name&gt; is the name of the app whose workspace you want to delete.

Note that workspaces can take up to three minutes to delete. There is a known issue where attempting to create a new workspace before the previous one has finished deleting can cause the new workspace to become stuck initializing.

Service (Database) Management Commands

To list the databases on Dash Enterprise:

de services list --type &lt;database-type&gt;

where &lt;database-type&gt; is redis, postgres, or 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 database attached:

de services exists --name &lt;app-name&gt; --type &lt;database-type&gt;

where &lt;app-name&gt; is the name of the app and &lt;database-type&gt; is redis or postgres.

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

To create and attach a database to an app:

de services create --name &lt;app-name&gt; --type &lt;database-type&gt;

where &lt;app-name&gt; is the name of the app that you want to attach the service to and &lt;database-type&gt; is redis or postgres.

To delete a database:

de services delete --name &lt;app-name&gt; --type &lt;database-type&gt;

where &lt;app-name&gt; is the name of the app whose database you want to delete and &lt;database-type&gt; is redis or postgres.

New in version 1.10.0

To set or update the memory limit of a Redis or Postgres database (requires the admin role):

de services update --name &lt;app-name&gt; --type &lt;database-type&gt; --memory-limit &lt;memory-limit&gt;

where &lt;app-name&gt; is the name of the app that the database belongs to, &lt;database-type&gt; is redis or postgres, and &lt;memory-limit&gt; is the memory limit that you want to set in MiB (maximum 24576).

Adding, Updating, and Removing Environment Variables

To add an environment variable:

de apps update --name &lt;app-name&gt; --add-environment-variable &lt;env-var&gt;

where &lt;app-name&gt; is the name of the app that you want to edit and &lt;env-var&gt; 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 &lt;app-name&gt; --add-environment-variable &lt;env-var&gt;

where &lt;app-name&gt; is the name of the app that you want to edit and &lt;env-var&gt; 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 &lt;app-name&gt; --remove-environment-variable &lt;env-var-key&gt;

where &lt;app-name&gt; is the name of the app that you want to edit and &lt;env-var-key&gt; is the key of the environment variable you want to remove.

Changing the Python Version

New in version 1.10.0

To change the Python version and rebuild for the change to take effect:

de apps update --name &lt;app-name&gt; --python-version &lt;version&gt; --rebuild

where &lt;app-name&gt; is the name of the app and &lt;version&gt; is the Python version (major and minor only) that you want the app to use. For example, 3.11.

See the supported Python versions.

Enabling and Disabling the Persistent Filesystem

To enable the persistent filesystem:

de apps update --name &lt;app-name&gt; --persistent-filesystem

where &lt;app-name&gt; is the name of the app that you want to edit.

To disable the persistent filesystem:

de apps update --name &lt;app-name&gt; --no-persistent-filesystem

where &lt;app-name&gt; is the name of the app that you want to edit.

Editing Replicas

New in version 1.10.0

To edit the replicas for an app’s autoscaling web process:

de apps update --name &lt;app-name&gt; --process-name web --min-replicas &lt;min-replicas&gt; --max-replicas &lt;max-replicas&gt;

where: * &lt;app-name&gt; is the name of the app whose web process replicas you want to edit. * &lt;min-replicas&gt; is the minimum number of replicas that you want to set (must be an integer greater than or equal to 1, cannot be greater than &lt;max-replicas&gt;). * &lt;max-replicas&gt; is the maximum number of replicas that you want to set (must be an integer greater than or equal to 1, cannot be less than &lt;min-replicas&gt;).

Set the minimum and maximum replicas to the same value or use --replicas to disable autoscaling.

To edit the replicas for an app’s non-autoscaling web process (or any non-web process):

de apps update --name &lt;app-name&gt; --process-name &lt;process-name&gt; --replicas &lt;replicas&gt;

where: * &lt;app-name&gt; is the name of the app whose process replicas you want to edit. * &lt;process-name&gt; is the name of the process. * &lt;replicas&gt; is the number of replicas that you want to set for the process (must be an integer greater than or equal to 1).

Tip: If you do not supply --process-name, the web process is assumed.

Setting a Custom Memory Limit

New in version 1.10.0

To set a custom memory limit for an app’s process:

de apps update --name &lt;app-name&gt; --process-name &lt;process-name&gt; --memory-limit &lt;new-limit&gt;

where: * &lt;app-name&gt; is the name of the app. * &lt;process-name&gt; is the name of the app process whose memory limit you want to change. * &lt;new-limit&gt; is the memory limit that you want to set, in MiB (maximum 24576). For example, --memory-limit 3072.

Tip: If you do not supply --process-name, the web process is assumed.

Adding and Removing Co-Owners

To add a single co-owner:

de apps update --name &lt;app-name&gt; --add-co-owner &lt;username&gt;

where &lt;app-name&gt; is the name of the app that you want to edit and &lt;username&gt; 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 &lt;app-name&gt; --add-group-co-owner &lt;group-name&gt;

where &lt;app-name&gt; is the name of the app that you want to edit and &lt;group-name&gt; 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 &lt;app-name&gt; --remove-co-owner &lt;username&gt;

where &lt;app-name&gt; is the name of the app that you want to edit and &lt;username&gt; 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 &lt;app-name&gt; --remove-group-co-owner &lt;group-name&gt;

where &lt;app-name&gt; is the name of the app that you want to edit and &lt;group-name&gt; is the name of the group whose members you want to remove as co-owners.

Changing the App Viewer Access Level

To change the viewer access level to Restricted:

de apps update --name &lt;app-name&gt; --view-access restricted

where &lt;app-name&gt; 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 &lt;app-name&gt; --view-access authenticated

where &lt;app-name&gt; 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 &lt;app-name&gt; --view-access unauthenticated

where &lt;app-name&gt; 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 &lt;app-name&gt; --add-viewer &lt;username&gt;

where &lt;app-name&gt; is the name of the app that you want to edit and &lt;username&gt; 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 &lt;app-name&gt; --add-group-viewer &lt;group-name&gt;

where &lt;app-name&gt; is the name of the app that you want to edit and &lt;group-name&gt; is the name of the group whose members you want to add as viewers.

To remove a single viewer:

de apps update --name &lt;app-name&gt; --remove-viewer &lt;username&gt;

where &lt;app-name&gt; is the name of the app that you want to edit and &lt;username&gt; 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 &lt;app-name&gt; --remove-group-viewer &lt;group-name&gt;

where &lt;app-name&gt; is the name of the app that you want to edit and &lt;group-name&gt; is the name of the group whose members you want to remove as viewers.

Changing the App Visibility in the Portal and Portal Rank

To make an app visible in the Portal:

de apps update --name &lt;app-name&gt; --visible-on-portal

where &lt;app-name&gt; is the name of the app whose portal visibility you want to change.

To change an app’s rank in the Portal:

de apps update --name &lt;app-name&gt; --portal-rank &lt;rank&gt;

where &lt;app-name&gt; is the name of the app that you want to edit and &lt;rank&gt; is the rank that you want to set (must be an integer).

To make an app not visible in the Portal:

de apps update --name &lt;app-name&gt; --not-visible-on-portal

where &lt;app-name&gt; is the name of the app whose portal visibility you want to change.

Changing the App Information

To change an app’s title:

de apps update --name &lt;app-name&gt; --title &lt;new-title&gt;

where &lt;app-name&gt; is the name of the app that you want to edit and &lt;new-title&gt; 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.

To change an app’s description:

de apps update --name &lt;app-name&gt; --description "&lt;new-description&gt;"

where &lt;app-name&gt; is the name of the app that you want to edit and &lt;new-description&gt; is the description that you want to set.

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

To change an app’s thumbnail:

de apps update --name &lt;app-name&gt; --thumbnail &lt;path-to-file&gt;

where &lt;app-name&gt; is the name of the app that you want to edit and &lt;path-to-file&gt; 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.

To change the maintainer email for an app:

de apps update --name &lt;app-name&gt; --maintainer-email [email protected]

where &lt;app-name&gt; 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.

To add a tag:

de apps update --name &lt;app-name&gt; --tag &lt;tag-name&gt;

where &lt;app-name&gt; is the name of the app you want to edit and &lt;tag-name&gt; 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 &lt;app-name&gt; --remove-tag &lt;tag-name&gt;

where &lt;app-name&gt; is the name of the app you want to edit and &lt;tag-name&gt; 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 &lt;app-name&gt;

where &lt;app-name&gt; is the app whose processes and workspace you want to restart.

The output is similar to

Restarting workspace for app &lt;app-name&gt;
Restarting web for app &lt;app-name&gt;
Restarting worker for app &lt;app-name&gt;

Deleting Apps

To delete an app:

de apps delete --name &lt;app-name&gt;

where &lt;app-name&gt; is the name of the app you want to delete.

Data Source Management Commands

New in version 1.10.0

To test the connection to a data source that hasn’t been created yet:

de data-sources validate --type &lt;data-source-type&gt; --connection-info "&lt;credentials&gt;"

where: * &lt;data-source-type&gt; is the data source type. Supported types are amazon-redshift, amazon-s3, azure-data-lake, custom, custom-sql, databricks, google-big-query, and snowflake. * &lt;credentials&gt; is a JSON representation of the credentials for connecting to the data source.

To test the connection to an existing data source:

de data-sources validate --data-source &lt;data-source-name&gt;

where &lt;data-source-name&gt; is the name of the data source that you want to test connecting to.

To list the data sources on Dash Enterprise:

de data-sources list

A list of data sources that you have access to is displayed (if you have the admin role, all data sources are displayed).

The data sources are listed in descending creation date order. To filter the list, use --limit--offset--mine, or a combination. * de data-sources list --limit 5 limits the results to the first 5 data sources. * de data-sources list --offset 2 excludes the first 2 data sources. * de data-sources list --mine displays only the data sources that you own.

To check the existence of a data source by name:

de data-sources exists --data-source &lt;data-source-name&gt;

where &lt;data-source-name&gt; is the data source name that you want to look up.

If the data source is Restricted and you do not have access to it, nor do you have the admin role, the output is similar to Data source [restricted-data] does not exist on [example.plotly.host] regardless of whether the data source exists.

To create a data source:

de data-sources create --data-source &lt;data-source-name&gt; --type &lt;data-source-type&gt; --auth-method &lt;authentication-method&gt; --connection-info "&lt;credentials&gt;" --description "&lt;description&gt;"

where: * &lt;data-source-name&gt; is the name that you want to give to the new data source. * &lt;data-source-type&gt; is the data source type. Supported types are amazon-redshift, amazon-s3, azure-data-lake, custom, custom-sql, databricks, google-big-query, and snowflake. * &lt;authentication-method&gt; is the authentication method. Required for data source types that support more than one authentication method:
* Amazon Redshift: redshift-standard or aws-auth.
* Azure data lake: azure-microsoft-id or azure-sas-token.
* Databricks: databricks-pat (personal access token) or databricks-oauth (OAuth machine-to-machine). * &lt;credentials&gt; is a JSON representation of the credentials for connecting to the data source, respecting the information required by the authentication method, if applicable. * &lt;description&gt; is an optional description of the data source.

The data source is created with Restricted access by default. Use --viewers or --group-viewers to give access to specific users that have license seats. Alternatively, use --access authenticated to give access to all users with license seats. Note that an Authenticated data source cannot be changed to Restricted.

To view detailed information about an existing data source:

de data-sources info --data-source &lt;data-source-name&gt;

where &lt;data-source-name&gt; is the name of the data source.

To link a data source to an app:

de data-sources link --data-source &lt;data-source-name&gt; --name &lt;app-name&gt; --restart

where &lt;data-source-name&gt; is the name of the data source and &lt;app-name&gt; is the name of the app that you want to link it to. The app processes and workspace (if any) will restart for the change to take effect.

To unlink a data source from an app:

de data-sources unlink --data-source &lt;data-source-name&gt; --name &lt;app-name&gt; --restart

where &lt;data-source-name&gt; is the name of the data source and &lt;app-name&gt; is the name of the app that you want to unlink it from. The app processes and workspace (if any) will restart for the change to take effect.

To update a data source:

de data-sources update --data-source &lt;data-source-name&gt; &lt;parameters-to-update&gt; --restart

where &lt;data-source-name&gt; is the name of the data source and &lt;parameters-to-update&gt; is the information that you want to change about the data source (you can change more than one parameter at once). Supported changes are: * --auth-method &lt;new-authentication-method&gt; updates the data source’s authentication method.
* where &lt;new-authentication-method&gt; can be:
* Amazon Redshift: redshift-standard or aws-auth.
* Azure data lake: azure-microsoft-id or azure-sas-token.
* Databricks: databricks-pat (personal access token) or databricks-oauth (OAuth machine-to-machine). * --connection-info &lt;new-credentials&gt; updates the credentials used to connect to the data source. &lt;new-credentials&gt; must be a JSON representation of the new credentials for connecting to the data source, respecting the information required by the authentication method, if applicable. * --access authenticated changes a Restricted data source to Authenticated (all users with license seats can access it). An Authenticated data source cannot be changed back to Restricted. * --viewers &lt;username1,username2...&gt; or --group-viewers &lt;group1,group2...&gt; updates user access to a Restricted data source. Note that this is a replace operation, not an add operation. * --description "&lt;new-description&gt;" sets a new description for the data source.

The app processes and workspace (if any) will restart for the change to take effect.

To delete a data source:

de data-sources delete --data-source &lt;data-source-name&gt;

where &lt;data-source-name&gt; is the name of the data source that you want to delete. Add --yes to automatically answer the confirmation prompt.

Other Commands

Opening Dash and Dash Enterprise Documentation

To open Dash and Dash Enterprise documentation:

de docs

Your browser opens to https://&lt;your-dash-enterprise-server&gt;/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