Getting Started with the TestRail CLI

The TestRail CLI is an open source command-line tool that makes it easy to upload test automation results to your TestRail projects - without writing any code or dealing with APIs.

Use it to automate your reporting workflow by uploading results from popular frameworks like JUnit, TestNG, NUnit, Cypress, Playwright, and more.

You can now also integrate performance testing results - including those from JMeter - using the same CLI-based workflows. This is ideal for load testing, latency checks, or stress tests as part of your CI/CD pipeline.

The CLI supports both code-first and specification-first testing approaches:

• In a code-first setup, you define and run tests in code, and then sync results to TestRail.
• In a specification-first setup, you map test cases in TestRail ahead of execution and link results back to existing test IDs.

As an open source project, the TestRail CLI thrives on community feedback. You can raise defects, suggest improvements, and even propose new features via GitHub. Your contributions help shape the future of this tool.

Why use TestRail CLI?

Simplify your test automation reporting:

• Skip the API learning curve - just point to your XML test report and upload.
• Language-agnostic - works with any framework that outputs JUnit-style XML.
• CI/CD-friendly - easily scriptable for use in pipelines.
• Open source - hosted on GitHub; contribute or customize.

Supported frameworks

You can use the CLI with nearly any test automation framework that can export JUnit-style reports, including:

• Cypress.io
• Playwright
• JUnit
• TestNG
• NUnit
• Pytest
• Robot Framework
• JMeter

✅ If your framework supports JUnit-style XML output, it works with the TestRail CLI.

By parsing and uploading JUnit style test results into TestRail directly from the command line or by running the CLI as part of an automated build pipeline in Jenkins, GitLab CI, GitHub Actions, or other CI tools, you can focus on writing test code instead of having to worry about API calls and other technical details related to uploading test results.

For sample test automation projects with different frameworks, you can also see our Automation Frameworks Integration project on GitHub.

Example: Uploading Test Results to TestRail

Here’s a simple workflow for uploading results from a Playwright or JUnit test run into TestRail.

trcli --url <TESTRAIL_URL> \
      --project <PROJECT_NAME> \
      --suite <SUITE_NAME> \
      --milestone <MILESTONE_NAME> \
      --run-name "Automated Test Run - $(date +%Y-%m-%d)" \
      --results <PATH_TO_XML_REPORT>

<TESTRAIL_URL> - your TestRail instance URL

<PROJECT_NAME> - the name of your project in TestRail

<SUITE_NAME> - the test suite to upload results to

<MILESTONE_NAME> - optional milestone in TestRail

<PATH_TO_XML_REPORT> - path to your JUnit-style XML results file

Prerequisites

The TestRail CLI is programming-language agnostic when it comes to uploading your test results, but the tool itself is developed in Python and can be installed from the public Python Package Index (PyPI). 

Before installing the CLI, make sure:

• Python 3.10.4 or later is installed on your machine.
• pip (Python’s package manager) is available from your terminal.
• You have a TestRail account with administrator or API access.

Enable the TestRail API

• Go to Administration > Site Settings > API
• Check Enable API

Install Python 3.10+

Download Python 3.10.4 from python.org

During installation, ensure pip is included

python --version
pip --version

If those commands show version numbers, you can start installing TestRail CLI. Otherwise, follow these set up instructions: 

On Windows

1. Download Python from the official website.
2. During installation:
   • Check “Add Python to PATH”.
   • Ensure pip is selected.
3. Restart your terminal and run:

python --version
pip --version

On macOS

1- Install Homebrew (if not already installed):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2- Use Homebrew to install Python:

brew install python@3.10

3- Confirm installation:

python3 --version
pip3 --version

sudo apt update
sudo apt install python3.10 python3-pip

python3 --version
pip3 --version

$ pip install trcli

trcli

TestRail CLI v1.1X.X
Copyright 2025 Gurock Software GmbH - www.gurock.com
Supported and loaded modules:
    - parse_junit: JUnit XML Files (& Similar)
    - parse_robot: Robot Framework XML Files
    - parse_openapi: OpenAPI YML Files
    - add_run: Create a new test run