You are viewing documentation for our open source project which is maintained by the community. If you want to get started building assistants with Rasa please check out our latest [documentation here](/content/docs/index.html). ## Cheat Sheet | Command | Effect | |----------------------------|---------------------------------------------------------------------------------------| | `rasa init` | Creates a new project with example training data, actions, and config files. | | `rasa train` | Trains a model using your NLU data and stories, saves trained model in `./models`. | | `rasa interactive` | Starts an interactive learning session to create new training data by chatting to your assistant. | | `rasa shell` | Loads your trained model and lets you talk to your assistant on the command line. | | `rasa run` | Starts a server with your trained model. | | `rasa run actions` | Starts an action server using the Rasa SDK. | | `rasa visualize` | Generates a visual representation of your stories. | | `rasa test` | Tests a trained Rasa model on any files starting with `test_`. | | `rasa test e2e` | Runs end-to-end testing fully integrated with the action server that serves as acceptance testing.| | `rasa data split nlu` | Performs a 80/20 split of your NLU training data. | | `rasa data split stories` | Do the same as `rasa data split nlu`, but for your stories data. | | `rasa data convert` | Converts training data between different formats. | | `rasa data migrate` | Migrates 2.0 domain to 3.0 format. | | `rasa data validate` | Checks the domain, NLU and conversation data for inconsistencies. | | `rasa export` | Exports conversations from a tracker store to an event broker. | | `rasa evaluate markers` | Extracts markers from an existing tracker store. | | `rasa marker upload` | Upload marker configurations to Analytics Data Pipeline | | `rasa license` | Display licensing information. | | `rasa -h` | Shows all available commands. | ##### note If you run into character encoding issues on Windows like: `UnicodeEncodeError: 'charmap' codec can't encode character ...` or the terminal is not displaying colored messages properly, prepend `winpty` to the command you would like to run. For example `winpty rasa init` instead of `rasa init` ## Log Level Rasa produces log messages at several different levels (eg. warning, info, error and so on). You can control which level of logs you would like to see with `--verbose` (same as `-v`) or `--debug` (same as `-vv`) as optional command line arguments. See each command below for more explanation on what these arguments mean. In addition to CLI arguments, several environment variables allow you to control log output in a more granular way. With these environment variables, you can configure log levels for messages created by external libraries such as Matplotlib, Pika, and Kafka. These variables follow [standard logging level in Python](https://docs.python.org/3/library/logging.html#logging-levels). Currently, following environment variables are supported: 1. LOG_LEVEL_LIBRARIES: This is the general environment variable to configure log level for the main libraries Rasa uses. It covers Tensorflow, `asyncio`, APScheduler, SocketIO, Matplotlib, RabbitMQ, Kafka. 2. LOG_LEVEL_MATPLOTLIB: This is the specialized environment variable to configure log level only for Matplotlib. 3. LOG_LEVEL_RABBITMQ: This is the specialized environment variable to configure log level only for AMQP libraries, at the moment it handles log levels from `aio_pika` and `aiormq`. 4. LOG_LEVEL_KAFKA: This is the specialized environment variable to configure log level only for kafka. 5. LOG_LEVEL_PRESIDIO: This is the specialized environment variable to configure log level only for Presidio, at the moment it handles log levels from `presidio_analyzer` and `presidio_anonymizer`. 6. LOG_LEVEL_FAKER: This is the specialized environment variable to configure log level only for Faker. General configuration (`LOG_LEVEL_LIBRARIES`) has less priority than library level specific configuration (`LOG_LEVEL_MATPLOTLIB`, `LOG_LEVEL_RABBITMQ` etc); and CLI parameter sets the lowest level log messages which will be handled. This means variables can be used together with a predictable result. As an example: ```bash LOG_LEVEL_LIBRARIES=ERROR LOG_LEVEL_MATPLOTLIB=WARNING LOG_LEVEL_KAFKA=DEBUG rasa shell --debug ``` The above command run will result in showing: - messages with `DEBUG` level and higher by default (due to `--debug`) - messages with `WARNING` level and higher for Matplotlib - messages with `DEBUG` level and higher for kafka - messages with `ERROR` level and higher for other libraries not configured Note that CLI config sets the lowest level log messages to be handled, hence the following command will set the log level to `INFO` (due to `--verbose`) and no debug messages will be seen (library level configuration will not have any effect): ```bash LOG_LEVEL_LIBRARIES=DEBUG LOG_LEVEL_MATPLOTLIB=DEBUG rasa shell --verbose ``` As an aside, CLI log level sets the level at the root logger (which has the important handler - `coloredlogs` handler); this means even if an environment variable sets a library logger to a lower level, the root logger will reject messages from that library. If not specified, the CLI log level is set to `INFO`. ## Custom logging configuration ##### New in 3.4 The Rasa CLI now includes a new argument `--logging-config-file` which accepts a YAML file as value. You can now configure any logging formatters or handlers in a separate YAML file. The logging config YAML file must follow the [Python built-in dictionary schema](https://docs.python.org/3/library/logging.config.html#dictionary-schema-details), otherwise it will fail validation. You can pass this file as argument to the `--logging-config-file` CLI option and use it with any of the rasa commands. ## rasa init This command sets up a complete assistant for you with some example training data: ```bash rasa init ``` It creates the following files: ```bash . ├── actions │ ├── __init__.py │ └── actions.py ├── config.yml ├── credentials.yml ├── data │ ├── nlu.yml │ └── stories.yml ├── domain.yml ├── endpoints.yml ├── models │ └── .tar.gz └── tests └── test_stories.yml ``` It will ask you if you want to train an initial model using this data. If you answer no, the `models` directory will be empty. Any of the default CLI commands will expect this project setup, so this is the best way to get started. You can run `rasa train`, `rasa shell` and `rasa test` without any additional configuration. ## rasa train The following command trains a Rasa model: ```bash rasa train ``` If you have existing models in your directory (under `models/` by default), only the parts of your model that have changed will be re-trained. For example, if you edit your NLU training data and nothing else, only the NLU part will be trained. If you want to train an NLU or dialogue model individually, you can run `rasa train nlu` or `rasa train core`. If you provide training data only for one of these, `rasa train` will fall back to one of these commands by default. `rasa train` will store the trained model in the directory defined by `--out`, `models/` by default. The name of the model by default is `.tar.gz`. If you want to name your model differently, you can specify the name using the `--fixed-model-name` flag. By default validation is run before training the model. If you want to skip validation, you can use the `--skip-validation` flag. If you want to fail on validation warnings, you can use the `--fail-on-validation-warnings` flag. The `--validation-max-history` is analogous to the `--max-history` argument of `rasa data validate`. The following arguments can be used to configure the training process: ```bash usage: rasa train [-h] [-v] [-vv] [--quiet] [--logging-config-file LOGGING_CONFIG_FILE] [--data DATA [DATA ...]] [-c CONFIG] [-d DOMAIN] [--out OUT] [--dry-run] [--skip-validation] [--fail-on-validation-warnings] [--validation-max-history VALIDATION_MAX_HISTORY] [--augmentation AUGMENTATION] [--debug-plots] [--num-threads NUM_THREADS] [--fixed-model-name FIXED_MODEL_NAME] [--persist-nlu-data] [--force] [--finetune [FINETUNE]] [--epoch-fraction EPOCH_FRACTION] [--endpoints ENDPOINTS] {core,nlu} ... ``` **Positional arguments:** - `{core,nlu}` - `core` Trains a Rasa Core model using your stories. - `nlu` Trains a Rasa NLU model using your NLU data. **Optional arguments:** - `-h, --help` show this help message and exit - `--data DATA [DATA ...]` Paths to the Core and NLU data files. (default: ['data']) - `-c CONFIG, --config CONFIG` The policy and NLU pipeline configuration of your bot. (default: config.yml) - `-d DOMAIN, --domain DOMAIN` Domain specification. This can be a single YAML file, or a directory that contains several files with domain specifications in it. The content of these files will be read and merged together. (default: domain.yml) - `--out OUT` Directory where your models should be stored. (default: models) - `--dry-run` If enabled, no actual training will be performed. Instead, it will be determined whether a model should be re-trained and this information will be printed as the output. ... - (remaining options are similar) See the section on [data augmentation](https://legacy-docs-oss.rasa.com/docs/rasa/policies#data-augmentation) for info on how data augmentation works and how to choose a value for the flag. Note that `TEDPolicy` is the only policy affected by data augmentation. ### Incremental training ##### New in 2.2 This feature is experimental. We introduce experimental features to get feedback from our community, so we encourage you to try it out! However, the functionality might be changed or removed in the future. If you have feedback (positive or negative) please share it with us on the [Rasa Forum](https://forum.rasa.com/). In order to improve the performance of an assistant, it's helpful to practice [CDD](https://legacy-docs-oss.rasa.com/docs/rasa/conversation-driven-development) and add new training examples based on how your users have talked to your assistant. You can use `rasa train --finetune` to initialize the pipeline with an already trained model and further finetune it on the new training dataset that includes the additional training examples. This will help reduce the training time of the new model. By default, the command picks up the latest model in the `models/` directory. If you have a specific model which you want to improve, you may specify the path to this by running `rasa train --finetune `. Finetuning a model usually requires fewer epochs to train machine learning components like `DIETClassifier`, `ResponseSelector` and `TEDPolicy` compared to training from scratch. Either use a model configuration for finetuning which defines fewer epochs than before or use the flag `--epoch-fraction`. `--epoch-fraction` will use a fraction of the epochs specified for each machine learning component in the model configuration file. For example, if `DIETClassifier` is configured to use 100 epochs, specifying `--epoch-fraction 0.5` will only use 50 epochs for finetuning. You can also finetune an NLU-only or dialogue management-only model by using `rasa train nlu --finetune` and `rasa train core --finetune` respectively. To be able to fine tune a model, the following conditions must be met: 1. The configuration supplied should be exactly the same as the configuration used to train the model which is being finetuned. The only parameter that you can change is `epochs` for the individual machine learning components and policies. 2. The set of labels(intents, actions, entities and slots) for which the base model is trained should be exactly the same as the ones present in the training data used for finetuning. This means that you cannot add new intent, action, entity or slot labels to your training data during incremental training. You can still add new training examples for each of the existing labels. If you have added/removed labels in the training data, the pipeline needs to be trained from scratch. 3. The model to be finetuned is trained with `MINIMUM_COMPATIBLE_VERSION` of the currently installed rasa version. ## rasa interactive You can start an interactive learning session by running: ```bash rasa interactive ``` This will first train a model and then start an interactive shell session. You can then correct your assistants predictions as you talk to it. If [`UnexpecTEDIntentPolicy`](https://legacy-docs-oss.rasa.com/docs/rasa/policies#unexpected-intent-policy) is included in the pipeline, [`action_unlikely_intent`](https://legacy-docs-oss.rasa.com/docs/rasa/default-actions#action_unlikely_intent) can be triggered at any conversation turn. Subsequently, the following message will be displayed: ``` The bot wants to run 'action_unlikely_intent' to indicate that the last user message was unexpected ``` At this point in the conversation. Check out UnexpecTEDIntentPolicy docs to learn more. As the message states, this is an indication that you have explored a conversation path which is unexpected according to the current set of training stories and hence adding this path to training stories is recommended. Like other bot actions, you can choose to confirm or deny running this action. If you provide a trained model using the `--model` argument, training is skipped and that model will be loaded instead. During interactive learning, Rasa will plot the current conversation and a few similar conversations from the training data to help you keep track of where you are. You can view the visualization at http://localhost:5005/visualization.html as soon as the session has started. This diagram can take some time to generate. To skip the visualization, run `rasa interactive --skip-visualization`. ##### Add the `assistant_id` key introduced in 3.5 Running interactive learning with a pre-trained model whose metadata does not include the `assistant_id` will exit with an error. If this happens, add the required key with a unique identifier value in `config.yml` and re-run training. The following arguments can be used to configure the interactive learning session: ```bash usage: rasa interactive [-h] [-v] [-vv] [--quiet] [--logging-config-file LOGGING_CONFIG_FILE] [--e2e] [-p PORT] [-m MODEL] [--data DATA [DATA ...]] [--skip-visualization] [--conversation-id CONVERSATION_ID] [--endpoints ENDPOINTS] [-c CONFIG] [-d DOMAIN] [--out OUT] [--augmentation AUGMENTATION] [--debug-plots] [--finetune [FINETUNE]] [--epoch-fraction EPOCH_FRACTION] [--force] [--persist-nlu-data] {core} ... [model-as-positional-argument] ``` **Positional arguments:** - `{core}` - Starts an interactive learning session model to create new training data for a Rasa Core model by chatting. **Options:** - `-h, --help` show this help message and exit - `--e2e` Save story files in e2e format. In this format user messages will be included in the stories. (default: False) - `-p PORT, --port PORT` Port to run the server at. (default: 5005) - `-m MODEL, --model MODEL` Path to a trained Rasa model. If a directory is specified, it will use the latest model in this directory. (default: None) ... - (remaining options are similar) Train Arguments: - `-c CONFIG, --config CONFIG` The policy and NLU pipeline configuration of your bot. (default: config.yml) - `-d DOMAIN, --domain DOMAIN` Domain specification. This can be a single YAML file, or a directory that contains several files with domain specifications in it. The content of these files will be read and merged together. (default: domain.yml) - `--out OUT` Directory where your models should be stored. (default: models) ... ## rasa shell You can start a chat session by running: ```bash rasa shell ``` By default, this will load up the latest trained model. You can specify a different model to be loaded by using the `--model` flag. If you start the shell with an NLU-only model, `rasa shell` will output the intents and entities predicted for any message you enter. If you have trained a combined Rasa model but only want to see what your model extracts as intents and entities from text, you can use the command `rasa shell nlu`. To increase the logging level for debugging, run: ```bash rasa shell --debug ``` ##### note In order to see the typical greetings and/or session start behavior you might see in an external channel, you will need to explicitly send `/session_start` as the first message. Otherwise, the session start behavior will begin as described in [Session configuration](https://legacy-docs-oss.rasa.com/docs/rasa/domain#session-configuration). The following arguments can be used to configure the command. Most arguments overlap with `rasa run`; see the [following section](https://legacy-docs-oss.rasa.com/docs/rasa/command-line-interface/#rasa-run) for more info on those arguments. Note that the `--connector` argument will always be set to `cmdline` when running `rasa shell`. This means all credentials in your credentials file will be ignored, and if you provide your own value for the `--connector` argument it will also be ignored. ```bash usage: rasa shell [-h] [-v] [-vv] [--quiet] [--logging-config-file LOGGING_CONFIG_FILE] [--conversation-id CONVERSATION_ID] [-m MODEL] [--log-file LOG_FILE] [--use-syslog] [--syslog-address SYSLOG_ADDRESS] [--syslog-port SYSLOG_PORT] [--syslog-protocol SYSLOG_PROTOCOL] [--endpoints ENDPOINTS] [-i INTERFACE] [-p PORT] [-t AUTH_TOKEN] [--cors [CORS ...]] [--enable-api] [--response-timeout RESPONSE_TIMEOUT] [--request-timeout REQUEST_TIMEOUT] [--remote-storage REMOTE_STORAGE] [--ssl-certificate SSL_CERTIFICATE] [--ssl-keyfile SSL_KEYFILE] [--ssl-ca-file SSL_CA_FILE] [--ssl-password SSL_PASSWORD] [--credentials CREDENTIALS] [--connector CONNECTOR] [--jwt-secret JWT_SECRET] [--jwt-method JWT_METHOD] [--jwt-private-key JWT_PRIVATE_KEY] {nlu} ... [model-as-positional-argument] ``` **Positional arguments:** - `{nlu}` - Interprets messages on the command line using your NLU model. **Options:** - `-h, --help` show this help message and exit - `--conversation-id CONVERSATION_ID` Set the conversation ID. (default: 2a2364bb0b0d448a96b737fd398c766e) - `-m MODEL, --model MODEL` Path to a trained Rasa model. If a directory is specified, it will use the latest model in this directory. (default: models) ... - (remaining options are similar) **Server Settings:** - `-i INTERFACE, --interface INTERFACE` Network interface to run the server on. (default: 0.0.0.0) - `-p PORT, --port PORT` Port to run the server at. (default: 5005) ... ## rasa run To start a server running your trained model, run: ```bash rasa run ``` By default the Rasa server uses HTTP for its communication. To secure the communication with SSL and run the server on HTTPS, you need to provide a valid certificate and the corresponding private key file. You can specify these files as part of the `rasa run` command. If you encrypted your keyfile with a password during creation, you need to add the `--ssl-password` as well. ```bash rasa run --ssl-certificate myssl.crt --ssl-keyfile myssl.key --ssl-password mypassword ``` Rasa by default listens on each available network interface. You can limit this to a specific network interface using the `-i` command line option. ```bash rasa run -i 192.168.69.150 ``` Rasa will by default connect to all channels specified in your credentials file. To connect to a single channel and ignore all other channels in your credentials file, specify the name of the channel in the `--connector` argument. ```bash rasa run --connector rest ``` The name of the channel should match the name you specify in your credentials file. For supported channels see [the page about messaging and voice channels](https://legacy-docs-oss.rasa.com/docs/rasa/messaging-and-voice-channels). The following arguments can be used to configure your Rasa server: ```bash usage: rasa run [-h] [-v] [-vv] [--quiet] [--logging-config-file LOGGING_CONFIG_FILE] [-m MODEL] [--log-file LOG_FILE] [--use-syslog] [--syslog-address SYSLOG_ADDRESS] [--syslog-port SYSLOG_PORT] [--syslog-protocol SYSLOG_PROTOCOL] [--endpoints ENDPOINTS] [-i INTERFACE] [-p PORT] [-t AUTH_TOKEN] [--cors [CORS ...]] [--enable-api] [--response-timeout RESPONSE_TIMEOUT] [--request-timeout REQUEST_TIMEOUT] [--remote-storage REMOTE_STORAGE] [--ssl-certificate SSL_CERTIFICATE] [--ssl-keyfile SSL_KEYFILE] [--ssl-ca-file SSL_CA_FILE] [--ssl-password SSL_PASSWORD] [--credentials CREDENTIALS] [--connector CONNECTOR] [--jwt-secret JWT_SECRET] [--jwt-method JWT_METHOD] [--jwt-private-key JWT_PRIVATE_KEY] {actions} ... [model-as-positional-argument] ``` **Positional arguments:** - `{actions}` - Runs the action server. - `model-as-positional-argument` Path to a trained Rasa model. If a directory is specified, it will use the latest model in this directory. (default: None) **Options:** - `-h, --help` show this help message and exit - `-m MODEL, --model MODEL` Path to a trained Rasa model. If a directory is specified, it will use the latest model in this directory. (default: models) ... - (remaining options are similar) ## rasa visualize To generate a graph of your stories in the browser, run: ```bash rasa visualize ``` If your stories are located somewhere other than the default location `data/`, you can specify their location with the `--stories` flag. The following arguments can be used to configure this command: ```bash usage: rasa visualize [-h] [-v] [-vv] [--quiet] [--logging-config-file LOGGING_CONFIG_FILE] [-d DOMAIN] [-s STORIES] [--out OUT] [--max-history MAX_HISTORY] [-u NLU] ``` **Options:** - `-h, --help` show this help message and exit - `-d DOMAIN, --domain DOMAIN` Domain specification. This can be a single YAML file, or a directory that contains several files with domain specifications in it. The content of these files will be read and merged together. (default: domain.yml) - `-s STORIES, --stories STORIES` File or folder containing your training stories. (default: data) ... ## rasa test To evaluate a model on your test data, run: ```bash rasa test ``` This will test your latest trained model on any end-to-end stories you have defined in files with the `test_` prefix. If you want to use a different model, you can specify it using the `--model` flag. To evaluate the dialogue and NLU models separately, use the commands below: ```bash rasa test core ``` and ```bash rasa test nlu ``` You can find more details on specific arguments for each testing type in [Evaluating an NLU Model](https://legacy-docs-oss.rasa.com/docs/rasa/testing-your-assistant#evaluating-an-nlu-model) and [Evaluating a Dialogue Management Model](https://legacy-docs-oss.rasa.com/docs/rasa/testing-your-assistant#evaluating-a-dialogue-model). The following arguments are available for `rasa test`: ```bash usage: rasa test [-h] [-v] [-vv] [--quiet] [--logging-config-file LOGGING_CONFIG_FILE] [-m MODEL] [-s STORIES] [--max-stories MAX_STORIES] [--endpoints ENDPOINTS] [--fail-on-prediction-errors] [--url URL] [--evaluate-model-directory] [-u NLU] [-c CONFIG [CONFIG ...]] [-d DOMAIN] [--cross-validation] [-f FOLDS] [-r RUNS] [-p PERCENTAGES [PERCENTAGES ...]] [--no-plot] [--successes] [--no-errors] [--no-warnings] [--out OUT] ``` **Positional arguments:** - `{core,nlu}` - `core` Tests Rasa Core models using your test stories. - `nlu` Tests Rasa NLU models using your test NLU data. **Options:** - `-h, --help` show this help message and exit - `-m MODEL, --model MODEL` Path to a trained Rasa model. If a directory is specified, it will use the latest model in this directory. (default: models) - `--no-plot` Don't render evaluation plots. (default: False) ... ## rasa test e2e Rasa Pro Only ##### Rasa Pro License You'll need a license to get started with Rasa Pro. [Get it here](/content/rasa-pro-developer-edition-license-key-request/index.html) ##### New in 3.5 You can now use end-to-end testing to test your assistant as a whole, including dialogue management and custom actions. To run [end-to-end testing](https://legacy-docs-oss.rasa.com/docs/rasa/testing-your-assistant#end-to-end-testing) on your trained model, run: ```bash rasa test e2e ``` This will test your latest trained model on any end-to-end test cases you have. If you want to use a different model, you can specify it using the `--model` flag. The following arguments are available for `rasa test e2e`: ```bash usage: rasa test e2e [-h] [-v] [-vv] [--quiet] [--logging-config-file LOGGING_CONFIG_FILE] [--fail-fast] [-o] [--remote-storage REMOTE_STORAGE] [-m MODEL] [--endpoints ENDPOINTS] [path-to-test-cases] ``` **Optional arguments:** - `-h, --help` show this help message and exit - `-o, --e2e-results` Results file containing end-to-end testing summary. (default: None) ... ## rasa data split To create a train-test split of your NLU training data, run: ```bash rasa data split nlu ``` This will create a 80/20 split of train/test data by default. You can specify the training data, the fraction, and the output directory using the following arguments: ```bash usage: rasa data split nlu [-h] [-v] [-vv] [--quiet] [--logging-config-file LOGGING_CONFIG_FILE] [-u NLU] [--training-fraction TRAINING_FRACTION] [--random-seed RANDOM_SEED] [--out OUT] ``` **Options:** - `-h, --help` show this help message and exit - `-u NLU, --nlu NLU` File or folder containing your NLU data. (default: data) - `--training-fraction TRAINING_FRACTION` Percentage of the data which should be in the training data. (default: 0.8) ... **Python Logging Options:** You can control level of log messages printed. In addition to these arguments, a more fine grained configuration can be achieved with environment variables. See online documentation for more info. Please report your findings on any discrepancies or missing information that may seem relevant to your Rasa setup.