# Command line tool

## Use Cases

We've added the  `testmace-cli` console utility for running tests right from a TestMace project for you to improve automated processes, including API testing. Its possible use cases are:

* Quick testing without GUI after changing the API implementation;
* Running tests automatically before making a commit in the version control system;
* Running tests while automatic integration or CI/CD delivery;
* Regular scheduled testing for API operativity and stability monitoring.

## Installation

### NPM package

Make sure your system has [node.js](https://nodejs.org/en/) version 10 or higher installed.

To install the tool, run the following command:

```
npm install --global @testmace/cli
```

## Running the tool

The simplest way to run the tests is shown below.

Use the following command to test a local project:

```
testmace-cli <full_path_to_project>
```

Use the following command to test a cloud project:

```
testmace-cli -p <project_id> -t <access_token>
```

If all tests are successful, the 0 code will be returned, otherwise you'll see the 1 code. By default, tests results are printed to stdout.

### Run parameters

The tool supports the following run parameters:

* `-e <project_environment_name>` and `--environment <project_environment_name>` - allow to specify what environment variables to use while running tests. The name should correspond to one of the project's environments.
* `-r <reporter_type>` and `--reporter <reporter_type>` - allow to specify what kind of test reports you want to see.  You can use `junit`

  as `reporter_type`, which generates the result in the JUnit XML format.
* `-p <project_id>` or `--project <project_id>` - a cloud project identifier . You can find it on the particular project cloud sync control panel.
* `-t <access_token>` or `--token <access_token>` - an authorization token that you need to use the cloud sync feature. You can manage authorisation tokens in the user's profile on the cloud sync control panel.

## JUnit XML report

If you run the program with the  `--reporter=junit` key, the report will be generated in the JUnit XML format. It gives you a more detailed report of successful and failed requests and tests. Reports of this kind can be visualized by special programs (e. g. [XUnit Viewer](https://github.com/lukejpreston/xunit-viewer)) and CI/CD systems (e.g. [Jenkins](https://jenkins.io/)).

In reports each running node in the project tree is represented as *TestSuite*.The name corresponds to the relative path to your project root. For the `Link` node you should specify the relative path to the link node.  *properties*  here are the keys and values of this node's variables. Every test and HTTP-request is represented as*TestCase* in report&#x73;*.*

### An example of report visualization

![](/files/-LnHMEVGfotlyDmYMRCZ)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.testmace.com/cli/cli.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.