CLI commands reference

General reference

TRCLI is a command-line tool to automate actions in TestRail like creating test runs, uploading results, or generating cases from external reports.

Use this when:

• You want to automate QA workflows from local scripts or CI/CD pipelines
• You want faster, repeatable actions without needing to use the TestRail UI

The most basic command to shows help information for available options and commands:

trcli --help

which will retrieve a list like the following:

TestRail CLI v1.1X.X
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli [OPTIONS] COMMAND [ARGS]...

  TestRail CLI

Options:
  -c, --config           Optional path definition for testrail-credentials
                         file or CF file.
  -h, --host             Hostname of instance.
  --project              Name of project the Test Run should be created under.
  --project-id           Project id. Will be only used in case project name
                         will be duplicated in TestRail  [x>=1]
  -u, --username         Username.
  -p, --password         Password.
  -k, --key              API key used for authenticating with TestRail. This
                         must be used in conjunction with --username. If
                         provided, --password is not required.
  -v, --verbose          Output all API calls and their results.
  --verify               Verify the data was added correctly.
  --insecure             Allow insecure requests.
  -b, --batch-size       Configurable batch size.  [default: (50); x>=2]
  -t, --timeout          Batch timeout duration.  [default: (60); x>=0]
  -y, --yes              answer 'yes' to all prompts around auto-creation
  -n, --no               answer 'no' to all prompts around auto-creation
  -s, --silent           Silence stdout
  --proxy                Proxy address and port (e.g.,
                         http://proxy.example.com:8080).
  --proxy-user           Proxy username and password in the format
                         'username:password'.
  --noproxy              Comma-separated list of hostnames to bypass the proxy
                         (e.g., localhost,127.0.0.1).
  --parallel-pagination  Enable parallel pagination for faster case fetching
                         (experimental).
  --help                 Show this message and exit.

Commands:
  add_run         Add a new test run in TestRail
  export_gherkin  Export BDD test case from TestRail as .feature file
  import_gherkin  Upload or update Gherkin .feature file in TestRail
  labels          Manage labels in TestRail
  parse_cucumber  Parse Cucumber JSON results and upload to TestRail
  parse_junit     Parse JUnit report and upload results to TestRail
  parse_openapi   Parse OpenAPI spec and create cases in TestRail
  parse_robot     Parse Robot Framework report and upload results to...
  references      Manage references in TestRail
  update          Update TRCLI to the latest version from PyPI.

Global options

These options can be used with any TRCLI command.

Commands summary

Create a new test run in TestRail

Use trcli add_run command when you want to create a test run in TestRail - either for manual execution or before uploading automated results. You can also use it to define scheduling, assign testers, or tag the run with references or requirements.

This is useful for:

• QA managers or testers planning work in advance
• Automation engineers needing a run ID before uploading results
• Teams aligning test runs with requirements, milestones, or sprint dates

Example

trcli add_run \
  --title "Release 2.3 Regression" \
  --suite-id 7 \
  --milestone-id 14 \
  --run-start-date "08/01/2025" \
  --run-end-date "08/05/2025" \
  --run-include-all \
  --run-refs REQ-101,REQ-202 \
  --run-assigned-to-id 3

This command creates a titled test run under suite ID 7, linked to a milestone, with a scheduled date range and all test cases included. The run is assigned to a specific tester and references two requirements.

Available options

TestRail CLI v1.1X.X
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli add_run [OPTIONS]

  Add a new test run in TestRail

Options:
  --title                     Title of Test Run to be created or updated in
                              TestRail.
  --run-id                    ID of existing test run to update. If not
                              provided, a new run will be created.  [x>=1]
  --suite-id                  Suite ID to submit results to.  [x>=1]
  --run-description           Summary text to be added to the test run.
  --milestone-id              Milestone ID to which the Test Run should be
                              associated to.  [x>=1]
  --run-start-date            The expected or scheduled start date of this
                              test run in MM/DD/YYYY format
  --run-end-date              The expected or scheduled end date of this test
                              run in MM/DD/YYYY format
  --run-assigned-to-id        The ID of the user the test run should be
                              assigned to.  [x>=1]
  --clear-run-assigned-to-id  Clear the assignee of the test run (only valid
                              when updating with --run-id).
  --run-include-all           Use this option to include all test cases in
                              this test run.
  --auto-close-run            Use this option to automatically close the
                              created run.
  --run-case-ids              Comma separated list of test case IDs to include
                              in the test run (i.e.: 1,2,3,4).
  --run-refs                  A comma-separated list of
                              references/requirements (up to 250 characters)
  --run-refs-action           Action to perform on references: 'add'
                              (default), 'update' (replace all), or 'delete'
                              (remove all or specific)
  -f, --file                  Write run data to file.
  --help                      Show this message and exit.

Tips

• If you want to limit the run to specific cases, use --run-case-ids.
• For scheduled work, QA managers can define a start/end date for visibility.
• If you're automating test uploads, you can create the run here and later use parse_junit with --run-id.

Add labels to Test Cases

The labels command lets you create, update, delete, and manage labels in TestRail. Labels are useful for organizing test cases, grouping related tests, and enabling easier filtering during reporting.

This command is available starting with TestRail CLI v1.12.0.

Example

## assign a label to a case
trcli labels cases add --project-id <PROJECT_ID> --case-id <CASE_ID> --label "Regression"

## delete a lable from a case
trcli labels delete --project-id <PROJECT_ID> --id <LABEL_ID>

## gets details of a specific label
trcli labels get --project-id <PROJECT_ID> --id <LABEL_ID>

## list all the labels from a specific project
trcli labels list --project-id <PROJECT_ID>

## update an existing label
trcli labels update --project-id <PROJECT_ID> --id <LABEL_ID> --name "Updated Label Name"

Available options

TestRail CLI v1.12.0
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli labels [OPTIONS] COMMAND [ARGS]...

  Manage labels in TestRail

Options:
  --help  Show this message and exit.

Commands:
  add     Add a new label in TestRail
  cases   Manage labels for test cases
  delete  Delete labels from TestRail
  get     Get a specific label by ID
  list    List all labels in the project
  update  Update an existing label in TestRail

When to use labels

• Organization - Group test cases by feature, module, or release cycle.
• Filtering - Easily filter reports and test runs by label.
• Automation - Assign labels automatically to categorize tests during CI/CD pipelines.

Upload JUnit results

Parses a JUnit XML report (common in automated tests) and uploads the results to TestRail.

Use parse_junit to parse a JUnit XML report and upload test results into TestRail. This is commonly used in CI/CD pipelines or after automated test execution.

You’d use this when:

• You’ve run automated tests (e.g., JUnit, TestNG, Selenium)
• You want results uploaded directly to TestRail
• You want to auto-create missing cases or update an existing test run

The test_id property in a JUnit <testcase> can reference one or multiple TestRail case IDs.

When multiple case IDs are provided (as a comma-separated list), the TestRail CLI creates an individual result for each referenced case in the target test run.

Example

trcli parse_junit \
  -f build/test-results/test/TEST-results.xml \
  --project "Mobile App" \
  --title "Regression Test - Aug 1" \
  --suite-id 10 \
  --milestone-id 22 \
  --case-matcher "name" \
  --update-existing-cases yes \
  --test-run-ref "PROJ-123,PROJ-456"
  --close-run

This command uploads results from a JUnit XML file, creates a test run under the given suite, associates it with a milestone, matches test cases by title, and closes the run afterward.

Available Options

TestRail CLI v1.1X.X
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli parse_junit [OPTIONS]

  Parse JUnit report and upload results to TestRail

Options:
  -f, --file                Filename and path.
  --close-run               Close the newly created run
  --title                   Title of Test Run to be created or updated in
                            TestRail.
  --case-matcher            Mechanism to match cases between the report and
                            TestRail.
  --suite-id                Suite ID to submit results to.  [x>=1]
  --suite-name              Suite name to submit results to.
  --run-id                  Run ID for the results they are reporting
                            (otherwise the tool will attempt to create a new
                            run).  [x>=1]
  --plan-id                 Plan ID with which the Test Run will be
                            associated.  [x>=1]
  --config-ids              Comma-separated configuration IDs to use along
                            with Test Plans (i.e.: 34,52).
  --milestone-id            Milestone ID to which the Test Run should be
                            associated to.  [x>=1]
  --section-id              Section ID to create new sections with test cases
                            under (optional).  [x>=1]
  --run-description         Summary text to be added to the test run.
  --case-fields             List of case fields and values for new test cases
                            creation. Usage: --case-fields type_id:1 --case-
                            fields priority_id:3
  --result-fields           List of result fields and values for test results
                            creation. Usage: --result-fields
                            custom_field_a:value1 --result-fields
                            custom_field_b:3
  --allow-ms                Allows using milliseconds for elapsed times.
  --special-parser          Optional special parser option for specialized
                            JUnit reports.
  -a, --assign              Comma-separated list of user emails to assign
                            failed test results to.
  --test-run-ref            Comma-separated list of reference IDs to append to
                            the test run (up to 250 characters total).
  --json-output             Output reference operation results in JSON format.
  --update-existing-cases   Update existing TestRail cases with values from
                            JUnit properties (default: no).
  --update-strategy         Strategy for combining incoming values with
                            existing case field values, whether to append or
                            replace (default: append).
  --help                    Show this message and exit.

Mapping a Test Result to multiple TestRail Cases

A JUnit test case can be mapped to multiple TestRail cases using the test_id property.

<testcase classname="tests.LoginTests" name="test_login_flow">
  <properties>
    <property name="test_id" value="C101, C102, C103"/>
  </properties>
</testcase>

When the results are processed by trcli parse_junit:

• The CLI reads the comma-separated list of case IDs
• Each case receives an individual result entry
• All mapped cases receive the same result status from the automation test

This allows a single automated test to update multiple TestRail cases while maintaining separate result tracking for each case.

Tips

• Use --run-id if you already created a test run using add_run.
• Use --case-matcher to link results to existing test cases, avoiding duplicates.
• Pair --plan-id and --config-ids if you’re managing test matrices (e.g., platform/browser combos).
• --result-fields can capture metadata like build versions or defect links.
• -a, --assign will retrieve an output similar to: Assigning failed results: 1/1, Done.

Generate test cases from an OpenAPI Spec

Use this command to automatically create test cases in TestRail based on an OpenAPI (formerly Swagger) specification. This is ideal for quickly building test coverage for REST APIs.

You’d use this if:

• You’re launching a new API and want to bootstrap test case creation
• You want structured test cases for endpoints (GET/POST/etc.) based on a spec file
• You want to align test coverage with your API design

Example

trcli parse_openapi \
  -f specs/user-api.yaml \
  --suite-id 5 \
  --case-fields type_id:1 \
  --case-fields priority_id:3

This reads user-api.yaml, generates test cases into suite ID 5, and sets type and priority values for each new case.

Available options

TestRail CLI v1.1X.X
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli parse_openapi [OPTIONS]

  Parse OpenAPI spec and create cases in TestRail

Options:
  -f, --file      Filename and path.
  --suite-id      Suite ID to create the tests in (if project is multi-suite).
                  [x>=1]
  --case-fields   List of case fields and values for new test cases creation.
                  Usage: --case-fields type_id:1 --case-fields priority_id:3
  --help          Show this message and exit.

Tips

• Use --case-fields to tag cases with test type, automation status, or priority.
• If your project only uses a single suite, you can skip --suite-id.
• The generated cases will follow your TestRail custom fields and case template setup.

Upload Robot Framework results

Use this command to upload results from a Robot Framework test execution (typically an output.xml file) into TestRail.

Use it when:

• You're using Robot Framework for test automation
• You want results to be reflected in TestRail automatically
• You want to auto-create test cases or link results to existing runs/plans

Example

trcli parse_robot \
  -f output.xml \
  --project "Hardware QA" \
  --suite-name "Peripheral Tests" \
  --title "Regression - Aug 1" \
  --milestone-id 12 \
  --close-run \
  --case-matcher title

This command uploads test results from output.xml, creates a test run in the "Peripheral Tests" suite, links it to a milestone, matches cases by title, and closes the run afterward.

Available options

TestRail CLI v1.1X.X
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli parse_robot [OPTIONS]

  Parse Robot Framework report and upload results to TestRail

Options:
  -f, --file          Filename and path.
  --close-run         Close the newly created run
  --title             Title of Test Run to be created or updated in TestRail.
  --case-matcher      Mechanism to match cases between the report and
                      TestRail.
  --suite-id          Suite ID to submit results to.  [x>=1]
  --suite-name        Suite name to submit results to.
  --run-id            Run ID for the results they are reporting (otherwise the
                      tool will attempt to create a new run).  [x>=1]
  --plan-id           Plan ID with which the Test Run will be associated.
                      [x>=1]
  --config-ids        Comma-separated configuration IDs to use along with Test
                      Plans (i.e.: 34,52).
  --milestone-id      Milestone ID to which the Test Run should be associated
                      to.  [x>=1]
  --section-id        Section ID to create new sections with test cases under
                      (optional).  [x>=1]
  --run-description   Summary text to be added to the test run.
  --case-fields       List of case fields and values for new test cases
                      creation. Usage: --case-fields type_id:1 --case-fields
                      priority_id:3
  --result-fields     List of result fields and values for test results
                      creation. Usage: --result-fields custom_field_a:value1
                      --result-fields custom_field_b:3
  --allow-ms          Allows using milliseconds for elapsed times.
  --help              Show this message and exit.

Tips

• Use --case-matcher to prevent creating duplicate cases.
• Combine --plan-id and --config-ids when integrating with Test Plans and Configurations.
• Use --run-id to update a run that was previously created via add_run.

Manage References

The references command lets you manage external requirement references associated with your TestRail test cases directly from the command line.

This is useful when you need to link or update requirement IDs (e.g., Jira tickets, requirement specs) across multiple test cases in bulk - without having to open each test case in the TestRail UI.

You can use trcli references to:

• Add Jira story links (REQ-123, STORY-456) to existing test cases.
• Remove outdated references in bulk.
• Replace legacy requirement tags with new ones when product specifications change.

This feature is especially useful for teams integrating TestRail with external requirement tracking tools or maintaining traceability across multiple QA projects.

Prerequisites

Before running reference commands:

• You must have TestRail CLI installed and configured with valid API credentials.
• You must have edit access to the TestRail project and test cases.
• Know the Test Case IDs and reference values you want to manage.

Command Overview

TestRail CLI v1.xx.x
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli references cases [OPTIONS] COMMAND [ARGS]...

  Manage references for test cases

Options:
  --help  Show this message and exit.

Commands:
  add     Add references to test cases
  delete  Delete all or specific references from test cases
  update  Update references on test cases by replacing existing ones

1. Add References to Test Cases

Adds one or more requirement references to the specified test cases.

trcli references cases add --case-ids <CASE_IDS> --refs <REFERENCES>

Mac (zsh/bash) and Windows (PowerShell) syntax are the same.

Example

# Add requirement IDs REQ-101 and REQ-102 to test cases 5 and 6
trcli references cases add --case-ids 5,6 --refs REQ-101,REQ-102

Parameters

TestRail CLI v1.xx.x1
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli references cases add [OPTIONS]

  Add references to test cases

Options:
  --case-ids   Comma-separated list of test case IDs (e.g., 1,2,3).
               [required]
  --refs       Comma-separated list of references to add (e.g., REQ-1,REQ-2).
               [required]
  --help       Show this message and exit.

2. Delete References from Test Cases

Deletes specific references from test cases, or all references if none are specified.

Command

trcli references cases delete --case-ids <CASE_IDS> [--refs <REFERENCES>] [--yes]

Example

# Delete references REQ-101 and REQ-102 from test cases 5 and 6
trcli references cases delete --case-ids 5,6 --refs REQ-101,REQ-102

# Delete all references from test cases 5 and 6 (confirmation required)
trcli references cases delete --case-ids 5,6

⚠️ Warning: Without --refs, all references for the specified test cases will be removed.
Use --yes to skip the confirmation prompt in automated scripts.

Parameters

TestRail CLI v1.xx.x
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli references cases delete [OPTIONS]

  Delete all or specific references from test cases

Options:
  --case-ids   Comma-separated list of test case IDs (e.g., 1,2,3).
               [required]
  --refs       Comma-separated list of specific references to delete. If not
               provided, all references will be deleted.
  --yes        Confirm the action without prompting.
  --help       Show this message and exit.

3. Update References on Test Cases

Description

Replaces all existing references on the specified test cases with the provided new ones.

trcli references cases update --case-ids <CASE_IDS> --refs <REFERENCES>

Example

# Replace all references on test cases 5 and 6 with REQ-200 and REQ-201
trcli references cases update --case-ids 5,6 --refs REQ-200,REQ-201

💡 Tip: Use this command to perform controlled updates when requirement IDs are reorganized or renamed.

Parameters

TestRail CLI v1.xx.x
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli references cases update [OPTIONS]

  Update references on test cases by replacing existing ones

Options:
  --case-ids   Comma-separated list of test case IDs (e.g., 1,2,3).
               [required]
  --refs       Comma-separated list of references to replace existing ones
               (e.g., REQ-1,REQ-2).  [required]
  --help       Show this message and exit.

Where to get help

• Official TRCLI documentation
• GitHub: testrail-cli
• TestRail Full System Documentation