notice

This is documentation for Rasa X/Enterprise Documentation v1.1.x, which is no longer actively maintained.
For up-to-date documentation, see the latest version (1.4.x).

Version: 1.1.x

rasactl

rasactl is a command line interface tool (CLI) tool for deploying and managing Rasa Enterprise deployments.

note

rasactl is open-source and available in the rasactl repository. Please create an issue in this repository if you discover bugs or have suggestions for improvements.

You can use rasactl to:

  • Deploy Rasa Enterprise.
  • Upgrade or change the configuration of a Rasa Enterprise deployment.
  • Manage the lifecycle of a running Rasa Enterprise deployment. You can start, stop or delete any Rasa Enterprise deployments managed by rasactl.

In addition, for deployments on a KIND cluster (see REI) you can:

  • Connect a local Rasa Open Source server to Rasa Enterprise; rasactl will prepare configuration for Rasa Open Source and Rasa Enterprise and run the Rasa Open Source server on local machine. This feature requires that a compatible version of Rasa Open Source is installed locally.

  • Use a local Rasa project with a Rasa Enterprise deployment; You can connect to a local Rasa project instead of to a Git repository. This setup was previously referred to as "local mode" in older Rasa Enterprise versions. Using a local Rasa project requires Rasa Enterprise ≥ 1.0.0.

Before you start

Below you can find several things that are good to know and keep in mind when you use rasactl.

It is possible to configure multiple deployments with rasactl. A rasactl command will always execute an operation on a single deployment. Here is the order in which rasactl determines which deployment to use:

  1. A DEPLOYMENT-NAME passed as an argument in CLI, e.g. rasactl status deployment-name, you can use rasactl help command to see usage example for a given command.
  2. rasactl checks if a .rasactl file exists in the current working directory. If so, the deployment defined in the file is used. This .rasactl file is created automatically when the rasactl start --project command is executed.
  3. rasactl checks if a default deployment is configured in the rasactl.yaml configuration file, if yes, then the default deployment is used. The default deployment can be set by using the rasactl config use-deployment command.
  4. If there is only one deployment, then it's used.

You can use the rasactl list command to check which deployment is used as the current one.

The rasactl delete command requires explicitly passing a DEPLOYMENT-NAME as an argument.

  • rasactl uses the Rasa Enterprise Helm chart to deploy Rasa Enterprise.

  • rasactl deploys Rasa Enterprise without a Rasa Open Source server. It's up to you to connect Rasa Open Source with Rasa Enterprise deployment.

  • rasactl uses the current Kubernetes context from the kubeconfig file. If you want to switch Kubernetes clusters you have to use kubectl or use the --kube-context flag to switch used context.

Installation

rasactl comes as a part of the Rasa Simple Installation. If you'd like to install rasactl manually, below you can find instructions on how to do this.

$ curl -L https://github.com/RasaHQ/rasactl/releases/download/1.0.4/rasactl_1.0.4_darwin_amd64.tar.gz --output rasactl_1.0.4_darwin_amd64.tar.gz
$ tar -zxvf rasactl_1.0.4_darwin_amd64.tar.gz
$ sudo cp rasactl_1.0.4_darwin_amd64/rasactl /usr/local/bin/

Binary downloads of rasactl can be found on the Releases page. There you can find binaries for other OS and architectures.

Global flags

Below you can find global flags that can be used with every command.

Global Flags:
--config string config file (default is $HOME/.rasactl.yaml)
--debug enable debug output
-h, --help help for rasactl
--kube-context string name of the kubeconfig context to use
--kubeconfig string absolute path to the kubeconfig file (default "$HOME/.kube/config")
--verbose enable verbose outpu

Commands

CommandDescription
addadd existing Rasa Enterprise deployment
authmanage credentials for Rasa Enterprise
completiongenerate the autocompletion script for the specified shell
configmodify the configuration file
connectconnect a component to Rasa Enterprise
deletedelete Rasa Enterprise deployment
enterprisemanage Rasa Enterprise
helpHelp about any command
listlist deployments
logsprint the logs for a container in a pod
modelmanage models for Rasa Enterprise
openopen Rasa Enterprise in a web browser
startstart a Rasa Enterprise deployment
statusshow deployment status
stopstop Rasa Enterprise deployment
upgradeupgrade Rasa Enterprise deployment

rasactl add

This command adds existing Rasa Enterprise deployment to rasactl.

If you already have a Rasa Enterprise deployment that uses the Rasa Enterprise Helm chart you can add the deployment and control it via rasactl.

Usage:
rasactl add NAMESPACE [flags]
Examples:
# Add a Rasa Enterprise deployment that is deployed in the 'my-test' namespace.
$ rasactl add my-test
# Add a Rasa Enterprise deployment that is deployed in the 'my-test' namespace and
# a helm release name for the deployment is 'rasa-x-example'.
$ rasactl add my-test --rasa-x-release-name rasa-x-example
Flags:
-h, --help help for add
--rasa-x-release-name string a helm release name to manage (default "rasa-x")

rasactl auth

Manage credentials for Rasa Enterprise.

Usage:
rasactl auth [command]
Available Commands:
login authorize rasactl to access the Rasa Enterprise with user credentials
logout remove access credentials for an account
Flags:
-h, --help help for auth

rasactl auth login

Log in to Rasa Enterprise.

auth login stores credentials in an external credentials store, such as the native keychain of the operating system.

The following external credential stores will be used:

Usage:
rasactl auth login [DEPLOYMENT-NAME] [flags]
Examples:
# Login to the 'my-deployment' Rasa Enterprise deployment.
$ rasactl auth login my-deployment
# Login to Rasa Enterprise (login to the currently active deployment).
$ rasactl auth login
# Provide a password using STDIN.
# You can login non-interactively by using the --password-stdin flag to provide a password through STDIN.
# Using STDIN prevents the password from ending up in the shell’s history.
$ rasactl auth login --username me --password-stdin
Flags:
-h, --help help for login
-p, --password string password
--password-stdin read the password from stdin
-u, --username string username
Linux requirements

For Linux pass is used as credential storage and pass is required to be installed and configured before you use the rasactl auth command.

rasactl auth logout

Removes credentials from an external credentials store, such as the native keychain of the operating system.

Usage:
rasactl auth logout [DEPLOYMENT-NAME] [flags]
Examples:
# Remove access credentials (use the currently active deployment).
$ rasactl auth logout
# Remove access credentials for the 'my-deployment' deployment.
$ rasactl auth logout my-deployment
Flags:
-h, --help help for logout

rasactl completion

Generate the autocompletion script for rasactl for the specified shell. See each sub-command's help for details on how to use the generated script.

Usage:
rasactl completion [command]
Available Commands:
bash generate the autocompletion script for bash
fish generate the autocompletion script for fish
powershell generate the autocompletion script for powershell
zsh generate the autocompletion script for zsh
Flags:
-h, --help help for completion
Use "rasactl completion [command] --help" for more information about a command.

rasactl config

Modify the configuration file.

Usage:
rasactl config [command]
Aliases:
config, cfg, conf
Available Commands:
use-deployment set the current-deployment in the configuration file
Flags:
--create-file create the configuration file if it doesn't exist
-h, --help help for config

rasactl config use-deployment

Sets the current-deployment in the configuration file.

Usage:
rasactl config use-deployment DEPLOYMENT-NAME [flags]
Examples:
# Set the 'example' deployment as the current deployment.
$ rasactl config use-deployment example
Flags:
-h, --help help for use-deployment
Global Flags:
--config string config file (default is $HOME/.rasactl.yaml)
--create-file create the configuration file if it doesn't exist
--debug enable debug output
--kubeconfig string absolute path to the kubeconfig file (default "$HOME/.kube/config")
--verbose enable verbose output

rasactl connect

Connect a component to Rasa Enterprise.

Usage:
rasactl connect [command]
Available Commands:
rasa run Rasa Open Source server and connect it to the Rasa Enterprise deployment
Flags:
-h, --help help for connect
Global Flags:
--config string config file (default is $HOME/.rasactl.yaml)
--debug enable debug output
--kubeconfig string absolute path to the kubeconfig file (default "$HOME/.kube/config")
--verbose enable verbose output
Use "rasactl connect [command] --help" for more information about a command.

rasactl connect rasa

Run a local Rasa Open Source server and connect it to a Rasa Enterprise deployment.

The command prepares a configuration that's required to connect Rasa Enterprise deployment and run a local Rasa Open Source server.

It's required to have the 'rasa' command accessible by rasactl.

The command works only if Rasa Enterprise deployment runs on a local Kubernetes cluster managed with 'kind'.

Usage:
rasactl connect rasa [DEPLOYMENT-NAME] [flags]
Examples:
# Connect Rasa Open Source server to Rasa Enterprise deployment.
$ rasactl connect rasa
# Run a separate Rasa Open Source server for the Rasa Enterprise worker environment.
$ rasactl connect rasa --run-separate-worker
# Pass extra arguments to Rasa Open Source server.
$ rasactl connect rasa --extra-args="--debug"
Flags:
--extra-args strings extra arguments for Rasa Open Source server
-h, --help help for rasa
-p, --port int port to run the Rasa Open Source server at (default 5005)
--run-separate-worker runs a separate Rasa Open Source server for the worker environment

rasactl start

The start command creates a Rasa Enterprise deployment or starts a stopped deployment if a given deployment already exists.

Usage:
rasactl start [DEPLOYMENT-NAME] [flags]
Examples:
# Create a new Rasa Enterprise deployment with an autogenerated name.
$ rasactl start
# Create a Rasa Enterprise deployment with a defined name.
$ rasactl start my-deployment
# Create a new deployment if there is already one or more deployments.
# rasactl start --create
# Create a Rasa Enterprise deployment with custom configuration, e.g the following configuration changes a Rasa Enterprise version.
# All available values: https://github.com/RasaHQ/rasa-x-helm/blob/main/charts/rasa-x/values.yaml
$ rasactl start --values-file custom-configuration.yaml
# Create a Rasa Enterprise deployment with a defined password.
$ rasactl start --rasa-x-password mypassword
# Create a Rasa Enterprise deployment that uses a local Rasa project.
# The command is executed in a Rasa project directory.
$ rasactl start --project
Flags:
--create create a new deployment. If --project or --project-path is set, or there is no existing deployment, the flag is not required to create a new deployment
-h, --help help for start
-p, --project use the current working directory as a project directory, the flag is ignored if --project-path is used
--project-path string absolute path to the project directory mounted in kind
--rasa-x-chart-version string a helm chart version to use
--rasa-x-edge-release use the latest edge release of Rasa Enterprise
--rasa-x-password string Rasa Enterprise password (default "rasaxlocal")
--rasa-x-password-stdin read the Rasa Enterprise password from stdin
--rasa-x-release-name string a helm release name to manage (default "rasa-x")
--values-file string absolute path to the values file
--wait-timeout duration time to wait for Rasa Enterprise to be ready (default 10m0s)

rasactl stop

The stop command stops a running Rasa Enterprise deployment. The Rasa Enterprise deployment and all its components will be scaled down to 0.

Usage:
rasactl stop [DEPLOYMENT-NAME] [flags]
Examples:
# Stop a Rasa Enterprise deployment with the 'my-deployment' name.
$ rasactl stop my-deployment
# Stop a currently active Rasa Enterprise deployment.
# The command stops the currently active deployment.
# You can use the 'rasactl list' command to check which deployment is currently used.
$ rasactl stop
Flags:
-h, --help help for stop

rasactl delete

The delete command deletes a Rasa Enterprise deployment.

You can use the --prune flag to remove a namespace where Rasa Enterprise deployment is located.

Notice: If you want to free resources, or temporarily you don't need to run Rasa Enterprise deployment, you can stop a Rasa Enterprise deployment instead of deleting it. Stopping the Rasa Enterprise deployment will free resources, but keep the current configuration.

Usage:
rasactl delete DEPLOYMENT-NAME [flags]
Aliases:
delete, del
Examples:
# Delete the 'my-example' deployment.
$ rasactl delete my-example
# Prune the 'my-example' deployment, execute the command with the --prune flag deletes the whole namespace.
$ rasactl delete my-example --prune
Flags:
--force if true, delete resources and ignore errors
-h, --help help for delete
--prune if true, delete a namespace with a project

rasactl list

List all deployments.

$ rasactl list
CURRENT NAME STATUS RASA PRODUCTION RASA WORKER ENTERPRISE VERSION
hopeful-haibt Running 2.8.1 2.8.1 inactive 0.42.0
* vibrant-yalow Running 2.8.1 2.8.1 inactive 0.42.0

The * in the CURRENT field indicates a deployment that is used as default. It means that every time when you execute rasactl command without defining the deployment name, the deployment marked with * is used.

A deployment is marked as CURRENT if:

  • there is a .rasactl file that includes a deployment name in your current working directory. The file is automatically created if you run the rasactl start command with the --project or --project-path flag
  • there is only one deployment
  • you set the current deployment by using the rasactl config use-deployment command

rasactl status

Show the status of a deployment.

Usage:
rasactl status [DEPLOYMENT-NAME] [flags]
Examples:
# Show status for the 'example' deployment.
$ rasactl status example
# Show status for the 'example' deployment along with details.
$ rasactl status example --details
Flags:
-d, --details show detailed information, such as running pods, helm chart status
-h, --help help for status

Example output:

$ rasactl status vibrant-yalow
Name: vibrant-yalow
Status: Running
URL: http://vibrant-yalow.rasactl.localhost
Version: 0.42.0
Enterprise: inactive
Rasa production version: 2.8.1
Rasa worker version: 2.8.1
Project path: /home/ubuntu/test

rasactl logs

Print the logs for a container in a pod. If the pod has only one container, the container name is optional.

Usage:
rasactl logs [DEPLOYMENT-NAME] [POD] [flags]
Examples:
# Choose a pod and show logs for it (use the currently active deployment).
$ rasactl logs
# Show logs from pod rasa-x (use the currently active deployment).
$ rasactl logs rasa-x
# Show logs from pod rasa-x for the 'my-deployment' deployment.
$ rasactl logs my-deployment rasa-x
# Display only the most recent 10 lines of output in pod rasa-x
$ rasactl logs rasa-x --tail=10
# Return snapshot of previous terminated nginx container logs from pod rasa
$ rasactl logs -p -c nginx rasa
# Begin streaming the logs from pod rasa-x
$ rasactl logs -f rasa-x
Flags:
-c, --container string a container name
-f, --follow specify if the logs should be streamed
-h, --help help for logs
-p, --previous print the logs for the previous instance of the container in a pod if it exists
--tail int lines of recent log file to display. Defaults to -1 showing all log lines (default -1)

Enterprise Management Commands

You can manage an Enterprise license via rasactl.

Usage:
rasactl enterprise [command]
Available Commands:
activate activate an Enterprise license
deactivate deactivate an Enterprise license

rasactl enterprise activate

Activate an Enterprise license.

Usage:
rasactl enterprise activate [DEPLOYMENT-NAME] [flags]
Examples:
# Activate an Enterprise license (use the currently active deployment).
$ rasactl enterprise activate
# Activate an Enterprise license for the 'my-deployment' deployment.
$ rasactl enterprise activate my-deployment
# Provide an Enterprise license using STDIN.
# You can pass an Enterprise license non-interactively by using the --license-stdin flag to provide a license through STDIN.
# Using STDIN prevents the license from ending up in the shell’s history.
$ rasactl enterprise activate --license-stdin
Flags:
-h, --help help for activate
-l, --license string an Enterprise license
--license-stdin read an Enterprise license from stdin

rasactl enterprise deactivate

Deactivate an Enterprise license.

Usage:
rasactl enterprise deactivate [DEPLOYMENT-NAME] [flags]
Examples:
# Deactivate an Enterprise license (use the currently active deployment).
$ rasactl enterprise deactivate
# Deactivate an Enterprise license for the 'my-deployment' deployment.
$ rasactl enterprise deactivate my-deployment
Flags:
-h, --help help for deactivate

Model Management Commands

You can manage models in Rasa Enterprise via rasactl. Below is a list of commands that help with managing models:

$ rasactl help model
manage models for Rasa Enterprise
Usage:
rasactl model [command]
Available Commands:
delete delete a model from Rasa Enterprise
download download a model from Rasa Enterprise
list list models stored in Rasa Enterprise
tag tag a model in Rasa Enterprise
upload upload model to Rasa Enterprise

rasactl model delete

Delete a model from Rasa Enterprise.

Usage:
rasactl model delete [DEPLOYMENT-NAME] MODEL-NAME [flags]
Aliases:
delete, del
Examples:
# Delete the 'example-model' model (use the currently active deployment).
$ rasactl model delete example-model
# Delete the 'example-model' model for the 'my-deployment' deployment.
$ rasactl model delete my-deployment example-model
Flags:
-h, --help help for delete

rasactl model download

Download a model from Rasa Enterprise to your local machine.

Usage:
rasactl model download [DEPLOYMENT-NAME] MODEL-NAME [DESTINATION] [flags]
Examples:
# Download the 'example-model' model (use the currently active deployment).
# If the destination is not defined, the model will be stored in a current working directory.
$ rasactl model download example-model
# Download the 'example-model' model for the 'my-deployment' deployment
# and store it in the /tmp directory.
$ rasactl model download my-deployment example-model /tmp/example-model.tar.gz
Flags:
-h, --help help for download

rasactl model list

List all models stored in Rasa Enterprise.

Usage:
rasactl model list [DEPLOYMENT-NAME] [flags]
Aliases:
list, ls
Examples:
# List all models (use the currently active deployment).
$ rasactl model list
# List all models for the 'my-deployment' deployment.
$ rasactl model list my-deployment
Flags:
-h, --help help for list

rasactl model tag

Create a tag and assign it to a given model.

Rasa Enterprise allows multiple versions of an assistant to be run simultaneously and served to different users. By default, two environments are defined:

  • production
  • worker

If you want to activate a model you have to tag it as 'production'. Learn more here.

Usage:
rasactl model tag [DEPLOYMENT-NAME] MODEL-NAME TAG [flags]
Examples:
# Tag the 'my-model' model as 'production' (use the currently active deployment)
$ rasactl model tag my-model production
# Tag the 'my-model' with the 'test' tag within the 'my-deployment' deployment.
$ rasactl model tag my-deployment my-model test
Flags:
-h, --help help for tag

rasactl model upload

Upload a model to Rasa Enterprise.

Usage:
rasactl model upload [DEPLOYMENT-NAME] MODEL-FILE [flags]
Aliases:
upload, up
Examples:
# Upload the model.tar.gz model file to Rasa Enterprise (use the currently active deployment).
$ rasactl model upload model.tar.gz
# Upload the model.tar.gz model file to the 'my-deployment' deployment.
$ rasactl model upload my-deployment model.tag.gz
Flags:
-h, --help help for upload