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.
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.
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://<your-dash-enterprise-server>/packages">https://<your-dash-enterprise-server>/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.
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.2.5
Update the CLI by running:
pip install dash-enterprise-libraries --upgrade --upgrade-strategy eager --extra-index-url <a href="https://<your-dash-enterprise-server>/packages">https://<your-dash-enterprise-server>/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.
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
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.
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).
To check which user is currently logged in:
de whoami
The output is similar to
Logged in as [jessica] to [example.plotly.host].
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.
You must have a license seat to run the commands below.
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].
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.
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
.
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.
You must be the app owner or a co-owner, or have the admin
role, to run the commands below.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
To delete an app:
de apps delete --name <app-name>
where <app-name>
is the name of the app you want to delete.
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.
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/.
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
de-client
v1.9.0 or later.