Parameter Sources

Updated October 13, 2025 13:00

The TestRail CLI allows flexible configuration using multiple input methods. This helps QA teams integrate the CLI seamlessly into both local setups and automated CI/CD pipelines.

🎓 Level up your testing skills with TestRail Academy!
Explore free, self-paced courses to get the most out of TestRail.

👉 Start learning now

Why this matters

You might want to pass in parameters like your TestRail host, project, or credentials. Depending on your workflow, you may set them directly in the command line, through a config file, or via environment variables.

Understanding the priority order helps you avoid conflicts and unexpected behaviour.

Note: query parameter limit is set to 250 characters (by default).

Parameter hierarchy (highest to lowest)

Hierarchy	Source	When to use
1	CLI parameters	Immediate overrides; perfect for scripting or one-off runs.
2	Custom config file	For specific project or team-level settings.
3	Environment variables	Good for CI/CD or secure runtime config (e.g., secrets).
4	Default config file	For fallback or baseline settings.
5	Default value (built-in)	Used only when nothing else is set.

Using Configuration Files

Configuration files offer a structured way to set parameters and preferences in YAML format. You can use either:

Default config file: Automatically loaded if placed next to the CLI.
Custom config file: Manually specified using -c or --config.

Supported fields in `config.yml`

Authentication fields

These fields are required to connect securely to your TestRail instance.

Field name	Type	Description
`host`	`string`	The full URL of your TestRail instance (e.g., https://example.testrail.io)
`username`	`string`	TestRail login email (used for basic auth). Required unless using `key`
`password`	`string`	TestRail password. Optional if using an API key instead.
`key`	`string`	API key for authentication (alternative to username/password).

💡 Tip: Do not include passwords or keys in shared config files. Prefer environment variables for sensitive values.

Project and run targeting fields

These specify where in TestRail your results should be uploaded.

Field name	Type	Description
`project`	`string`	Name of the project to upload results to.
`project_id`	`number`	Use when project names are duplicated to ensure correct targeting. Optional
`suite_id`	`number`	Targets a specific test suite. Required for multi-suite projects. Optional
`run_id`	`number`	If set, updates an existing run instead of creating a new one.
`milestone_id`	`number`	Adds the test run to a specific milestone.

Input and file fields

These fields define the test result input and config file references

Field name	Type	Description
`file`	`string`	Path to your test result file (e.g., `.xml`). Required.
`config`	`string`	Path to a secondary (custom) configuration file if using `--config`.

Metadata fields

These fields help describe the run in TestRail.

Field name	Type	Description
`title`	`string`	Title of the test run to be created (e.g., `Regression Build 12.1`).
`run_description`	`string`	Adds a description to the run (e.g., CI job URL or context). Optional.

Output and logging fields

These control what the CLI prints or logs.

Field name	Type	Description
`verbose`	`boolean`	If true, outputs detailed logs of what's happening. Default: `false`.
`silent`	`boolean`	If true, suppresses all non-result outputs (quiet mode). Default: `false`.

💡 Tip: Use verbose for debugging and silent in CI to clean up logs.

Network and security fields

These control how the CLI handles network communication with TestRail

Field name	Type	Description
`verify`	`boolean`	When true, checks SSL certificates on HTTPS requests.Default: `true`.
`insecure`	`boolean`	If true, allows requests without SSL verification. Useful for test environments.

💡 Tip: Use insecure: true only for testing - not recommended in production.

Behaviour control fields

These affect how the CLI behaves during execution.

Field name	Type	Description
`auto_creation_response`	`boolean`	If true, auto-confirms prompts to create missing TestRail entities.
`close_run`	`boolean`	If true, closes the test run after uploading results. Default: `false`.
`--auto-close-run`	n/a	If present, closes automatically the run after uploading the results.

Performance tuning fields

These help control how results are processed and sent.

Field name	Type	Description
`batch_size`	`number`	Number of results to send in each batch. Default varies by system.
`timeout`	`number`	Seconds to wait for more results before terminating (float allowed).

💡 Tip: Tuning batch_size and timeout can improve performance in large test suites.

Advanced data mapping fields

These are useful for customizing or extending the upload process.

Field name	Type	Description
`case_fields`	`dict`	Custom field values to apply when creating test cases. Format: `key: value`.
`result_fields`	`dict`	Custom field values to apply when uploading results. Format: `key: value`.
`case_results_statuses`	`dict`	Maps your framework’s result labels (like `passed`, `failed`) to TestRail status IDs.

💡 Tip: These are key for aligning automated test tools with custom workflows in TestRail.

Configuration file example

host: https://fakename.testrail.io/
project: My TestRail Project
username: myuser@name.com
password: StrongP@ssword
file: PATH/result_file.xml
title: Automated Tests
config: PATH/alternate_config.yml
batch_size: 20
timeout: 5.5
auto_creation_response: true
case_fields: 
    type_id: 1,
    priority_id: 3
    custom_field_id: [2, 4]
case_result_statuses:
   passed: 7 # e.g., Automation Passed
   failure: 8 # e.g., Automation Failed
   error: 4 # Optional: for exceptions
   skipped: 3 # Optional: for skipped tests

Setting parameters with environment variables

Environment variables are a secure and CI-friendly way to configure the CLI. Each CLI option can be translated into an environment variable:

Naming Rule

Use TR_CLI_ followed by the uppercase parameter name.
Replace dashes (-) with underscores (_).

Examples:

--host or -h → TR_CLI_HOST
--project-id → TR_CLI_PROJECT_ID
--username → TR_CLI_USERNAME
--auto-creation-response → TR_CLI_AUTO_CREATION_RESPONSE

💡 Tip: Replace dashes (-) in parameter names with underscores (_) when converting to environment variable names.

How to set environment variables

# Windows cmd
set TR_CLI_PROJECT=project name

# Windows powershell
$env:TR_CLI_PROJECT="project name"

# Linux
export TR_CLI_PROJECT="project name" for Linux-like systems

💡 Tip: These are temporary for the session. Use shell profiles (like .bashrc or .zshrc) for persistence.

CLI vs Config vs Environment variables

Source Type	Use when...	Bets for	Pros	Cons
CLI Parameter	You need to override settings for a one-off run or in a script	Local tests, quick overrides	- Immediate control - Highest priority	- Not reusable - Harder to maintain in pipelines
Custom Config File	You want team- or project-specific settings versioned in your repo	Shared projects, dev teams	- Reusable - Easy to document - Supports complex setups	- Lower priority than CLI - Still needs to be passed via `--config`
Environment Variable	You want to keep secrets out of files, or configure CI/CD dynamically	CI/CD, secure secrets	- Secure (good for auth) - No file needed	- Less visible/debuggable - Session-based (not persistent)
Default Config File	You want fallback values without needing to pass anything	Simple local workflows	- Automatically picked up - Good default behaviour	- Lowest file-based priority - Easy to forget it exists
Default Value	You didn’t set anything (the CLI decides a safe fallback)	Simplicity, learning	- Zero setup for simple runs	- Unpredictable if configs are incomplete

Practical Recommendations

Scenario	Recommended Source	Why?
Local manual testing	Default config file + occasional CLI overrides	Easy to set up, override when needed
Team-shared test environments	Custom config file	Versioned, readable settings for all
CI/CD pipeline	Environment variables + fallback config file	Secure, scriptable, reproducible
One-off quick test	CLI parameter	No setup, just run it
Updating credentials securely	Environment variables	Keeps secrets out of config and CLI history
Dynamic or multi-project pipelines	Use CLI for key project IDs, env vars for auth	Separates runtime data from secrets