---
schema_version: "1"
id: 5ddb36be8699a6f5a156f2b8360441d6b622a66275c1a779a737d63321ee71b8
title: BAT CLI Reference
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/api-functional-monitoring/bat-command-reference.md
canonical_url: https://docs.mulesoft.com/api-functional-monitoring/bat-command-reference
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 8475129d4b3de528c122929df97af21a3d3d58ed8da82aaff55082a00ae8ae00
description: MuleSoft Documentation Site
latest: true
---
---
product: API Functional Monitoring
---

# BAT CLI Reference

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

BAT CLI provides an API Functional Monitoring command line interface through an integration with
Anypoint Platform. The command line interface lets you run tests locally and schedule monitors for
continuous API testing. You can schedule tests in the cloud using the CLI-xAPI.

This reference covers the syntax and key options you can use with the `bat` commands. Using the
`bat` commands, you can debug and run tests, get credentials for scheduling tests, schedule tests,
list test schedules, and perform additional operations.

For commands to execute successfully, the account under which BAT CLI logs in must have the required
permissions for the action the command is executing.

## Permissions Required

To use all of the `bat` commands to execute the corresponding actions in Anypoint Platform, you must
have the following permissions.

<table><colgroup><col> <col></colgroup><thead><tr><th>Permission</th><th>Actions</th></tr></thead><tbody><tr><td><p>Create Applications (Runtime Manager)</p></td><td><p>Create private locations</p></td></tr><tr><td><p>Delete Applications (Runtime Manager)</p></td><td><p>Delete private locations</p></td></tr><tr><td><p>Manage Settings (Runtime Manager)</p></td><td><p>Update private locations</p></td></tr><tr><td><p>View Environment</p></td><td><p>Log in using BAT CLI</p></td></tr><tr><td><p>View Organization</p></td><td><p>Use Secrets Manager through BAT CLI</p></td></tr><tr><td><p>Exchange Contributor (Exchange)</p></td><td><p>Create or modify a monitor; add or modify a schedule</p></td></tr><tr><td><p>Exchange Administrator (Exchange)</p></td><td><p>Create, modify, or delete a monitor; add, modify, or delete a schedule</p></td></tr></tbody><tfoot><tr><td><p>Grant access to secrets (Secrets Manager)</p></td><td><p>Use Secrets Manager</p></td></tr></tfoot></table>

## Login Options

To use the `bat` commands to execute API Functional Monitoring actions, you must first log in using
one of the following login methods.

### Login Using Connected Apps

`bat [login --client-id --client-secret [--profile=<value>] --host=<value>]`

This option logs in to an Anypoint Platform account using the client ID and client secret from a
connected app. This provides an alternative way to log in using MFA (multi-factor authentication) so
that a second factor is not required. MFA is now required for non-SSO accounts unless they are on
your organization’s exemption list. For information about connected apps, which are configured by
organization administrators, see [Connected Apps](https://docs.mulesoft.com/access-management/connected-apps-overview).

### Login Using a Username and Password

`bat [login --username=<value> [--profile=<value>] --host=<value>]`

This option logs in to an Anypoint Platform account using a username and password. It displays an
interactive command for the password.

`password for user [username]: <password>`

You can include the option `--password=<password>` in the `login` command.

## Execute Commands Stored in a File

`bat [<file> …​ | <option> …​]`

Where:

- `file` is the relative path to the path and file name.

  The file must have one of the following base names and one of the following extensions:

  - base file names: main, bat

  - extensions: .yaml, or .yml

    When you execute bat without any arguments, BAT reads the YAML in the current directory and runs
    the specified tests. You can create a `config` folder and add different configuration files in
    `config` for the environments.

- `bat ~/path/to/folder/`  
  Executes from the desired folder. BAT searches for and executes the `bat.yaml` and `main.dwl`
  files.

- `bat ./folder/file.dwl`  
  Executes using the desired file. The root of the project is the current folder. The root of the
  project is used to resolve imports and load libraries and files.

## `bat` Command Options

- `--help`

  Displays information about how to use the command.

- `--validate | -V`

  Validates the file or folder. Also works with `--config` to validate specific configurations.

- `--config=<name>`

  Selects a configuration file (from the `config` folder) and registers the result as a global
  variable.

- `--version`

  Prints to standard output the version numbers of installed BAT and wrapper. If the latest version
  is not installed, that version is downloaded.

- `--update`

  Updates the BAT CLI to the latest version and configures a `.bat-version` file in the current
  folder. The program always respects the `.bat-version` configuration when running tests. If the
  specified version is not installed, it is downloaded and installed before execution.

- `--debug`

  Sends troubleshooting information to standard output during an execution.

- `--track`

  Sends data from the local executions.

- `--bat-version=<version>`

  Executes BAT using the specified version.

- `--init-folder`

  Stores the files `exchange.json` and `main.dwl`, which you generate when you create a monitor in
  the current directory. Optional.

- `--init`

  Same as the `bat init` command, which sets up a basic project folder. The folder contains the
  following files:

  . ├── bat.yaml ├── config │   ├── default.dwl │   ├── devx.dwl │   ├── qax.dwl │   └── stgx.dwl
  └── tests └── HelloWorld.dwl

- `--password=<value>`

  The value is the password for the Anypoint Platform user name. If is not present, the value of the
  environment variable ANYPOINT\_PASSWORD is used. If a value for this variable is not set, the
  default password from credentials file is used.

- `--profile=<value>`

  Profile is:

  - The name of a profile for accessing an Anypoint Platform location and retaining the login
    information between BAT sessions. Using this option eliminates the need to relogin between
    sessions. Optional.

  - The name of a profile for scheduling a test that can be different from the BAT login profile you
    used. By default, BAT uses the login profile for scheduling. Optional.

  - If it is not present, the value of the environment variable ANYPOINT\_PROFILE is used. If a
    value for this variable is not set, the default profile is used.

- `--username=<value>`

  The value is an Anypoint Platform user name. If it is not present, the value of the environment
  variable ANYPOINT\_USERNAME is used. If a value for this variable is not set, the default username
  from the credentials file is used.

- `--useProxy`

  Use this option with each `bat` command if your system requires that you access Anypoint Platform
  through a proxy.

- `--client-id`

  The client ID from your connected app. You must use this option with the login command if you log
  in using a connected app.

- `--client-secret`

  The client secret from your connected app. You must use this option with the login command if you
  log in using a connected app.

## `bat` Commands

You can use the following `bat` commands to manage cloud integration and to schedule and configure
tests and monitors using Anypoint Platform.

- `init`

  Sets up a basic project folder with config files, HelloWorld basic test, and a yaml descriptor
  file.

- `schedule ls | list`

  List all of the schedules that exist in the given profile’s organization.

- `schedule create [--cron="<expression>"] [--location=<id>]`

  Create a scheduler using a cron expression and generating a ZIP file that includes the tests and
  all the files. If you do not enter a cron expression, tests are scheduled to run every 15 minutes.

- `schedule endpoint <monitor-URL> [--cron="<expression>"] [--name=<suiteName>] [--location=<id>] [--new-relic-license-key=<newRelicLicenseKey>] [--slack-webhook=<slackWebHook>] [--email-list=<emails>] [--sumo-logic-endpoint=<sumoLogicEndpoint>] [--pager-duty-routing-key=<pagerDutyRoutingKey>] [--custom-report-url=<customReportUrl>] [--custom-report-headers=<header1,header2,…​,headerN>] [--custom-report-transformation=<pathToDwlFile>][--init-folder] [--status-code=<code>]`

  Create a monitor in Exchange using a URL, such as the following example URL: `http://example.com`.
  Optionally, you can add options to generate the `bat.yaml` with different parameters.

  - `[--cron="<expression>"]` By default, tests are scheduled to run every 15 minutes. You can
    change with the cron expression.

  - `[--name="<suiteName>"]` To set the name of the suite.

  - `[--location="<id>"]` Set a specific location ID to the monitor.

  - `[--new-relic-license-key="<newRelicLicenseKey>"]` Add the New Relic report to the bat.yaml.

  - `[--slack-webhook="<slackWebHook>"]` Add the Slack report to the bat.yaml.

  - `[--sumo-logic-endpoint="<sumoLogicEndpoint>"]` Add the Sumo Logic report to the bat.yaml.

  - `[--pager-duty-routing-key="<pagerDutyRoutingKey>"]` Add the PagerDuty report to the bat.yaml.

  - `[--custom-report-url="<customReportUrl>"] [--custom-report-headers="<header1,header2,…​,headerN>"] | [--custom-report-transformation="<pathToDwlFile>"]`
    Add the custom report to the bat.yaml file and optionally you can add the transformation file.

  - `[--init-folder]` Store generated exchange.json, bat.yaml and main.dml in the current directory.

  - `[--status-code=<code>]` Use code as HTTP code for test templates.

- `schedule rm | remove <id>`

  Deletes a schedule by its ID.

- `schedule disable <id>` Disables the schedule that is identified by the specified ID.

- `schedule enable <id>`

  Enables the schedule that is identified by the specified ID. Use this command only when you want
  to enable a schedule that you have disabled with the `bat schedule disable <id>` command.

- `whoami`

  Prints basic user information to standard output. Other profiles can be used with the `--profile`
  option.

- `worker register [--name=<value>]`

  Generates a post with the machine name and create a dummy target.

- `worker unregister [--name=<value>]`

  Unregisters worker.

- `worker id`

  Gets worker ID.

- `location create <name>`

  Creates a private location in the given profile’s organization in Anypoint Platform. See
  [Monitoring the Endpoints of Public APIs](https://docs.mulesoft.com/api-functional-monitoring/afm-monitoring-public-apis) and
  [Monitoring the Endpoints of Private APIs](https://docs.mulesoft.com/api-functional-monitoring/afm-monitoring-private-apis) for more information about
  private and public locations.

- `location delete <id>`

  Deletes a private location from the list of private locations in the given profile’s organization
  in Anypoint Platform.

  `id`

  Specify the ID that identifies the location. You can obtain the ID by running the
  `bat location ls` command.

- `location ls|list`

  Lists the private and public locations that exist in the given profile’s organization in Anypoint
  Platform. This command replaces `target ls|list`.

- `location update <id>`

  Updates a location by its ID. If a new version of the worker available, updates the location using
  latest version. This option is valid only for Mule locations.

- `get_token`

  Returns the token for accessing Anypoint Platform in the credentials file. Requires that you first
  run `bat login` to generate a profile.

- `grant`

  Grants API Functional Monitoring permission to access a shared secret that is stored in Anypoint
  Secrets Manager. You must grant API Functional Monitoring permission to access any shared secret
  that you use in a test or to access a reporter.

  Run the `bat grant` command before configuring a test or a reporter to use a shared secret. The
  aliases that you create in the command are what you specify in tests and configurations for
  reporters.

  bat grant -g=MySecretGroupName
  -s=MyAlias1:MySecretName1,MyAlias2:MySecretName2,…,MyAliasN:MySecretNameN \[--forceUpdate\]

  \-g

  Specify the name of the group in Anypoint Secrets Manager in which the shared secret is stored.

  \-s

  Specify an alias, a colon, and the name of the shared secret. The alias can be any combination of
  alphanumeric characters. The name of the shared secret is the name that identifies the shared
  secret in the group. If you want to use a single command to grant the BAT CLI permission to use
  more than one shared secret from the same group, separate each `alias:name` pair with a comma.
  +The secret must be created in a secrets group that is in the same environment that you are using
  in the BAT CLI. To find out which environment you are using in the BAT CLI, run the command
  `bat whoami`. The output contains the ID for the environment. Run the command `bat environment ls`
  to list the environments that you have access to. Match the ID from the `bat whoami` command with
  one of the environments listed. If you need to switch to the environment that your secrets group
  is in, run the command bat environment switch name, where name is the name of the environment.

  \--forceUpdate

  Specify this option if API Functional Monitoring lost access to a shared secret and you need to
  grant access again.

- `execution ls|list`

  Lists the monitors that are running for the specified profile. If no profile is specified, the
  default profile is used. The monitors listed are all of those in the current environment and for
  the current profile that were written and started through the BAT CLI, and any that were created
  online in Anypoint Platform.

  The output looks like this:

  Last executions:

      daily-retail-test:1.0.1                  PASSED     10 seconds ago
      internal-run-api-check:1.0.0             PASSED     11 minutes ago

- `environment ls|list`

- `environment switch <name>`

  The two options `ls` and `list` list the environments that are available for the specified
  profile. If no profile is specified, the default profile is used.

  The `switch` option enables you to use one of the listed environments. Add the name of the
  environment to the end of the command, as in this example that uses the environment `Sandbox`:

  bat environment switch Sandbox

## BAT Command Examples

- Run multiple test files from the bat.yaml file.

  `bat bat.yaml`

- Run a single file.

  `bat ./test/myFile.dwl`

- Determine the installed version.

  `bat --version`

  Example output if you do not have the latest version is:

  Updating Version: You have an older BAT version. The new version is downloaded in
  /Users/<username>/.bat/bat-cli-1.0.51 Downloading version 1.0.51. Please
  wait\`....................... BAT Wrapper: 1.0.53 BAT Version: 1.0.51

## See Also

- [Scheduling Testing and Monitoring](https://docs.mulesoft.com/api-functional-monitoring/bat-schedule-test-task)

- [Using Secrets to Mask Sensitive Information in Monitors](https://docs.mulesoft.com/api-functional-monitoring/afm-mask-info-in-monitors)