# `rasactl` Documentation

`rasactl` is a command line interface tool (CLI) tool that deploys and manages Rasa X deployments.

## Features:

- **deploy Rasa X / Enterprise**  
You can use `rasactl` to deploy Rasa X / Enterprise on your local machine or a VM in one of the major cloud providers.
- **upgrade Rasa X / Enterprise**  
Upgrade/change configuration for an existing Rasa X deployment.
- **stop/delete/start a running Rasa X / Enterprise deployment**  
Manage the lifecycle of your deployment: you can stop, delete or start one of the Rasa X deployments managed by `rasactl`.
- **connect a local Rasa Open Source server to Rasa X / Enterprise**  
You can use your local Rasa Open Source server along with Rasa X / Enterprise. `rasactl` will prepare configuration for Rasa Open Source and Rasa X and run the Rasa Open Source server on your local machine.
  
  (requires kind and Rasa Open Source installed locally)
- **use a local Rasa project along Rasa X / Enterprise deployment**  
Use your local Rasa project along with Rasa X / Enterprise deployment. The `rasaxctl` provides an easy way to use your local Rasa project along with Rasa X / Enterprise.
- **This setup was previously referred to as "local mode" in older Rasa X versions.**  
  (requires `kind` and Rasa X ≥ `1.0.0`)

##### Note  
`rasactl` is open-source and available in [the rasactl repository](https://github.com/RasaHQ/rasactl). Please [create an issue](https://github.com/RasaHQ/rasactl/issues/new) in this repository if you discover bugs or have suggestions for improvements.

## 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 the `rasactl help` command to see usage example for a given command.
2. `rasactl` checks if a `.rasactl` file exists in a 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 X Helm chart to deploy Rasa X / Enterprise.
- `rasactl` deploys Rasa X / Enterprise without a Rasa Open Source server. It's up to you to connect Rasa Open Source with the Rasa X / Enterprise deployment.
- `rasactl` uses a Kubernetes context from the kubeconfig file, if you want to switch Kubernetes cluster 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**  
  
  Copy  
  ```
  $ curl -L https://github.com/RasaHQ/rasactl/releases/download/0.0.9/rasactl_0.0.9_darwin_amd64.tar.gz
  $ tar -zxvf rasactl_0.0.9_darwin_amd64.tar.gz
  $ cp rasactl_0.0.9_darwin_amd64/rasactl /usr/local/bin/
  ```

Binary downloads of `rasactl` can be found on [the Releases page](https://github.com/rasahq/rasactl/releases). 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 output

## Commands

| Command       | Description                                             |
|---------------|---------------------------------------------------------|
| `add`        | add existing Rasa X deployment                          |
| `auth`       | manage credentials for Rasa X / Enterprise             |
| `completion`  | generate the autocompletion script for the specified shell |
| `config`     | modify the configuration file                            |
| `connect`    | connect a component to Rasa X                           |
| `delete`     | delete Rasa X deployment                                |
| `enterprise` | manage Rasa Enterprise                                   |
| `help`       | Help about any command                                   |
| `list`       | list deployments                                        |
| `logs`       | print the logs for a container in a pod               |
| `model`      | manage models for Rasa X / Enterprise                   |
| `open`       | open Rasa X in a web browser                            |
| `start`      | start a Rasa X deployment                               |
| `status`     | show deployment status                                   |
| `stop`       | stop Rasa X deployment                                  |
| `upgrade`    | upgrade Rasa X deployment                               |

### rasactl add

This command adds existing Rasa X deployment to `rasactl`.
If you already have a Rasa X deployment that uses the Rasa X Helm chart you can add the deployment and control it via `rasactl`.

Usage:
```bash
rasactl add NAMESPACE [flags]
```

Examples:
```bash
# Add a Rasa X deployment that is deployed in the 'my-test' namespace.
$ rasactl add my-test

# Add a Rasa X 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 X / Enterprise.

Usage:
```bash
rasactl auth [command]
```

Available Commands:
- `login` authorize `rasactl` to access the Rasa X / Enterprise with user credentials
- `logout` remove access credentials for an account

Flags:
- `-h, --help` help for auth

### rasactl auth login

Log in to Rasa X / 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:

- On macOS: [Apple macOS Keychain Access](https://support.apple.com/en-gb/guide/keychain-access/welcome/mac)
- On Linux: [pass](https://www.passwordstore.org/)
- On Windows: [Microsoft Windows Credential Manager](https://support.microsoft.com/en-us/windows/accessing-credential-manager-1b5c916a-6a16-889f-8581-fc16e8165ac0)

Usage:
```bash
rasactl auth login [DEPLOYMENT-NAME] [flags]
```

Examples:
```bash
# Login to the 'my-deployment' Rasa X / Enterprise deployment.
$ rasactl auth login my-deployment

# Login to Rasa X / 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

### rasactl auth logout

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

Usage:
```bash
rasactl auth logout [DEPLOYMENT-NAME] [flags]
```

Examples:
```bash
# 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:
```bash
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:
```bash
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:
```bash
rasactl config use-deployment DEPLOYMENT-NAME [flags]
```

Examples:
```bash
# Set the 'example' deployment as the current deployment.
$ rasactl config use-deployment example
```

Flags:
- `-h, --help` help for use-deployment
- `--create-file` create the configuration file if it doesn't exist

### rasactl connect

Connect a component to Rasa X.

Usage:
```bash
rasactl connect [command]
```

Available Commands:
- `rasa run` Rasa Open Source server and connect it to the Rasa X deployment

Flags:
- `-h, --help` help for connect

### rasactl connect rasa

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

Usage:
```bash
rasactl connect rasa [DEPLOYMENT-NAME] [flags]
```

Examples:
```bash
# Connect Rasa Open Source server to Rasa X deployment.
$ rasactl connect rasa

# Run a separate Rasa Open Source server for the Rasa X 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 X deployment or starts a stopped deployment if a given deployment already exists.

Usage:
```bash
rasactl start [DEPLOYMENT-NAME] [flags]
```

Examples:
```bash
# Create a new Rasa X deployment with an autogenerated name.
$ rasactl start

# Create a Rasa X deployment with a defined name.
$ rasactl start my-deployment
```

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 X
- `--rasa-x-password string` Rasa X password (default "rasaxlocal")
- `--rasa-x-password-stdin` read the Rasa X 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 X to be ready (default 10m0s)

### rasactl stop

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

Usage:
```bash
rasactl stop [DEPLOYMENT-NAME] [flags]
```

Examples:
```bash
# Stop a Rasa X deployment with the 'my-deployment' name.
$ rasactl stop my-deployment

# Stop a currently active Rasa X deployment.
$ rasactl stop
```

Flags:
- `-h, --help` help for stop

### rasactl delete

The `delete` command deletes a Rasa X / Enterprise deployment.
You can use the `--prune` flag to remove a namespace where Rasa X deployment is located.

Usage:
```bash
rasactl delete DEPLOYMENT-NAME [flags]
```

Aliases:
- delete, del

Examples:
```bash
# 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.

Usage:
```bash
rasactl list
```

Example Output:
```bash
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:
```bash
rasactl status [DEPLOYMENT-NAME] [flags]
```

Examples:
```bash
# 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

### rasactl logs

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

Usage:
```bash
rasactl logs [DEPLOYMENT-NAME] [POD] [flags]
```

Examples:
```bash
# 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
```

Flags:
- `-c, --container string` a container name
- `-f, --follow` specify if the logs should be streamed
- `-h, --help` help for logs

## Enterprise Management Commands

You can manage an Enterprise license via `rasactl`.

Usage:
```bash
rasactl enterprise [command]
```

Available Commands:
- `activate` activate an Enterprise license
- `deactivate` deactivate an Enterprise license

### rasactl enterprise activate

Activate an Enterprise license.

Usage:
```bash
rasactl enterprise activate [DEPLOYMENT-NAME] [flags]
```

Examples:
```bash
# 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
```

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:
```bash
rasactl enterprise deactivate [DEPLOYMENT-NAME] [flags]
```

Examples:
```bash
# 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 X / Enterprise via `rasactl`. Below is a list of commands that help with managing models:

Usage:
```bash
rasactl help model
```

Available Commands:
- `delete` delete a model from Rasa X / Enterprise
- `download` download a model from Rasa X / Enterprise
- `list` list models stored in Rasa X / Enterprise
- `tag` tag a model in Rasa X / Enterprise
- `upload` upload model to Rasa X / Enterprise

### rasactl model delete

Delete a model from Rasa X / Enterprise.

Usage:
```bash
rasactl model delete [DEPLOYMENT-NAME] MODEL-NAME [flags]
```

Aliases:
- delete, del

Examples:
```bash
# 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 X / Enterprise to your local machine.

Usage:
```bash
rasactl model download [DEPLOYMENT-NAME] MODEL-NAME [DESTINATION] [flags]
```

Examples:
```bash
# 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 X / Enterprise.

Usage:
```bash
rasactl model list [DEPLOYMENT-NAME] [flags]
```

Aliases:
- list, ls

Examples:
```bash
# 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.

Usage:
```bash
rasactl model tag [DEPLOYMENT-NAME] MODEL-NAME TAG [flags]
```

Examples:
```bash
# 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 X / Enterprise.

Usage:
```bash
rasactl model upload [DEPLOYMENT-NAME] MODEL-FILE [flags]
```

Aliases:
- upload, up

Examples:
```bash
# Upload the model.tar.gz model file to Rasa X / 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