TestCollab CLI Command Reference

On this page

@testcollab/cli provides six commands for CI reporting, quality gates, build traceability, agent-driven execution, and Gherkin synchronization. This page documents the command surface in CLI version 1.17.0.

You are not expected to run all six commands. Choose the commands that match your workflow.

Core reporting path and optional extensions

Category	Command or step	When to use it
Core	tc createTestPlan	Create and assign the curated plan that will receive results.
Core, outside the CLI	Your test runner	Execute tests and write JUnit XML or Mochawesome JSON.
Core	tc report	Upload the result file to the created plan.
Alternative shortcut	tc report --auto-create	Replace createTestPlan when you intentionally want the result file to create project records and a plan.
Optional traceability	tc createBuild	Record build, commit, environment, and pipeline provenance before creating a linked plan.
Optional policy	tc gate	Let the complete TestCollab plan make a separate CI or release decision.
Optional agent workflow	tc getTestPlan	Give a plan's structured steps to an agent or script.
Optional BDD workflow	tc sync	Synchronize committed Gherkin feature files.

Default: tc createTestPlan -> your test runner -> tc report

createBuild and gate are opt-in. Neither is required to upload automated results.

The entries below are command references, not a sequence of steps to run in order.

Install and verify the CLI

The CLI requires Node.js 18 or later. Pin the package in CI so new releases cannot change a pipeline unexpectedly:

npm install -g @testcollab/cli@1.17.0
tc --help

In the current 1.17.0 package, tc --version can print the hardcoded value 1.0.0. Check the installed package version with npm instead:

npm list -g @testcollab/cli --depth=0

For a guided setup, see TestCollab CLI: Install and First Run.

Authentication and common options

Every command accepts the following options:

Option	Required	Description
--api-key <key>	No	TestCollab API token. It takes precedence over TESTCOLLAB_TOKEN.
--project <id>	Yes	Numeric TestCollab project ID.
--api-url <url>	No	API base URL. The default is https://api.testcollab.io.
-h, --help	No	Display help for the selected command.

Store the token in your CI provider's secret manager and expose it as an environment variable:

export TESTCOLLAB_TOKEN="your-token"

For an EU-hosted account, add this exact option to every TestCollab command that your chosen workflow runs. The CLI does not infer the region:

--api-url https://api-eu.testcollab.io

Core upload: tc report

Parses one JUnit XML or Mochawesome JSON file and uploads results. In the standard path, it receives the Test Plan ID created by tc createTestPlan. --auto-create is an alternative shortcut, not an additional standard step.

tc report \
  --project 123 \
  --test-plan-id 456 \
  --format junit \
  --result-file ./results.xml

Option	Required	Description
--project <id>	Yes	Project ID.
--test-plan-id <id>	Conditional	Existing Test Plan ID. Required unless --auto-create is used.
--format <type>	Yes	junit or mochawesome.
--result-file <path>	Yes	Path to one result file. Globs and directories are not expanded.
--skip-missing	No	Mark assigned plan cases missing from this result file as skipped.
--auto-create	Conditional	Create or reuse a CI Imported tag, suites, cases, a CI folder, and a new plan.
--build <idOrVersion>	No	Build ID or version for the new plan. Requires --auto-create; a missing version is created as a build.
--environment <name>	No	Environment stored only if --build creates a build. Requires --build.
--api-key <key>	No	Token override.
--api-url <url>	No	API base URL.

--test-plan-id and --auto-create are mutually exclusive. Both modes write TESTCOLLAB_TEST_PLAN_ID=<id> to tmp/tc_test_plan.

In existing-plan mode, result names need a supported case marker such as [TC-42], TC-42, id-42, or testcase-42. The case must be in the plan and assigned to the token owner. See Report Automated Test Results from Any Framework.

tc report is an uploader, not a test verdict. Failed test statuses do not give the command a failing exit code. Missing IDs, unmatched assignments, per-case update problems, and attachment failures can also be warnings while the command reaches exit 0. Read the summary and normally preserve the test runner's exit status. Use tc gate only if your team has deliberately chosen a separate TestCollab plan policy.

Optional policy: tc gate

Reads live execution records from a Test Plan run and exits nonzero when its quality criteria are not met. It is not required after tc report.

tc gate \
  --project 123 \
  --test-plan-id 456 \
  --fail-on failed,blocked \
  --min-pass-rate 95 \
  --require-complete

Option	Default	Description
--project <id>	Required	Project ID.
--test-plan-id <id>	Required	Test Plan ID to evaluate.
--fail-on <statuses>	failed	Comma-separated system or custom status names whose combined count is compared with --max-failed.
--max-failed <n>	0	Allow up to this many cases across all --fail-on statuses.
--min-pass-rate <pct>	None	Require passed / executed to reach this percentage. All non-unexecuted statuses are in the executed denominator.
--require-complete	Off	Fail when any case is still unexecuted. Skipped cases count as complete.
--config <id>	All	Evaluate one numeric Test Plan configuration ID. This is not a configuration file.
--regression <id>	Latest	Evaluate a specific internal run or regression record ID.
--wait <seconds>	0	Poll while cases are unexecuted until complete or the timeout is reached.
--poll-interval <seconds>	15	Polling interval when --wait is used.
--api-key <key>	Environment	Token override.
--api-url <url>	US API	API base URL.

After --wait expires, the gate evaluates the results it has. Pair waiting with --require-complete or another criterion if a timed-out partial run must fail. Without --require-complete, the default gate ignores unexecuted cases.

For examples and release-safety guidance, see Quality Gates in CI/CD.

Optional traceability: tc createBuild

Records or reuses the build a pipeline produced or deployed. It is not required for result uploads. Use CLI 1.15.0 or later for this command; version 1.17.0 is recommended for the full reference on this page.

tc createBuild \
  --project 123 \
  --version "2.14.0" \
  --environment "Staging" \
  --commit "8c51704" \
  --deployment-url "https://ci.example.com/runs/987"

Option	Required	Description
--project <id>	Yes	Project ID.
--version <version>	Conditional	Built or deployed version. Required when a recognized CI provider does not supply a build number.
--environment <name>	No	Deployment or test environment.
--deployment-url <url>	No	Link to the pipeline run or deployment.
--commit <sha>	No	Source commit SHA.
--commit-url <url>	No	Web link to the commit.
--repo-url <url>	No	Web link to the source repository.
--notes <text>	No	Free-text build note.
--api-key <key>	No	Token override.
--api-url <url>	No	API base URL.

Azure DevOps, GitHub Actions, GitLab CI, Bitbucket Pipelines, CircleCI, and Jenkins can supply version and other provenance fields through their environment variables. Explicit options take precedence. There is no --branch option.

Existing versions are reused without overwriting their metadata. On success, the command writes TESTCOLLAB_BUILD_ID=<id> to tmp/tc_build. See Link CI Test Results to a Build or Release.

Core plan setup: tc createTestPlan

Creates a ready Test Plan, adds cases selected by a CI tag, assigns the cases that have no default assignee to one user, and optionally links a build or release.

tc createTestPlan \
  --project 123 \
  --ci-tag-id 88 \
  --assignee-id 17

Option	Required	Description
--project <id>	Yes	Project ID.
--ci-tag-id <id>	Yes	Tag ID used to select cases.
--assignee-id <id>	Yes	Project user ID assigned to the execution. Use the report token owner for automated results. Applies only to the cases that carry no default assignee, unless you pass --override-assignees.
--override-assignees	No	Assign every case to --assignee-id, replacing the default assignees the test cases carry. Off by default. Requires CLI 1.19.0 or later.
--build <idOrVersion>	No	Existing build ID or exact version. The command fails rather than creating a missing build.
--release <id>	No	Positive numeric release ID. A release name or version is not accepted.
--api-key <key>	No	Token override.
--api-url <url>	No	API base URL.

Who the cases are assigned to

A test case can carry a default assignee. When this command adds the tagged cases to the new plan, each case brings that person with it.

# default: the cases keep their own default assignee,
# and user 7 gets only the cases that have none
tc createTestPlan --project 45 --ci-tag-id 12 --assignee-id 7

# override: every case in the plan goes to user 7
tc createTestPlan --project 45 --ci-tag-id 12 --assignee-id 7 --override-assignees

• Without the flag, the command matches the app, where the assignment rules fill in only what is still unassigned.
• With the flag, it matches the app's "Apply assignment rules to all test cases" checkbox.
• If every case already carries a default assignee and the flag is off, nothing is reassigned. The command says so in its output.

The "fill in only what is unassigned" behaviour comes from the API, so it applies to every CLI version. --override-assignees is the way to opt out of it, and it needs CLI 1.19.0 or later. On an older CLI, upgrade rather than trying to work around it.

On success, the command writes TESTCOLLAB_TEST_PLAN_ID=<id> to tmp/tc_test_plan.

Optional agent input: tc getTestPlan

Fetches plan metadata, all plan cases, their steps and expected results, and available configuration results as JSON. Use it for an agent-driven workflow, not as a required reporting step.

tc getTestPlan \
  --project 123 \
  --test-plan-id 456 \
  --output ./tmp/test-plan.json

Option	Required	Description
--project <id>	Yes	Project ID.
--test-plan-id <id>	Yes	Test Plan ID to fetch.
--output <path>	No	Write JSON to an existing directory instead of standard output.
--api-key <key>	No	Token override.
--api-url <url>	No	API base URL.

Without --output, JSON goes to stdout and progress goes to stderr. A zero-case plan produces a warning and valid JSON with an empty testCases array. See Fetch a Test Plan as JSON for AI Agents.

Optional BDD workflow: tc sync

Synchronizes committed Gherkin .feature files in the current Git repository with TestCollab. Features become suites, scenarios become cases, and Git commits track the synchronization state. It is independent of result uploading.

tc sync --project 123

Option	Required	Description
--project <id>	Yes	Project ID.
--api-key <key>	No	Token override.
--api-url <url>	No	API base URL.

Run the command inside a Git repository. Only content in commits is considered; staged, modified, and untracked .feature changes are listed in a warning and are not synchronized. Set BDD_SYNC_DEBUG=1 only when support asks for extra synchronization diagnostics.

Keep raw sync logs private and ensure your CI masks the token. Current 1.17.0 builds print the synchronization request URL, which can include authentication query details. Rotate the token if an unredacted log was exposed. See Keeping Test Cases in Sync with Your Local Repository.

Environment variables

Variable	Commands	Purpose
TESTCOLLAB_TOKEN	All six	Recommended API token source. An explicit --api-key overrides it.
BDD_SYNC_DEBUG=1	sync	Enables additional feature-sync diagnostic output.
Provider CI variables	createBuild	Used to infer version, commit, links, and repository where supported. Explicit flags override detected values.

report, gate, createTestPlan, and getTestPlan do not infer a project, plan, release, or region from CI variables.

Exit codes

Command	Code	Meaning
report, createBuild, createTestPlan, getTestPlan, sync	0	The command reached successful completion. Review warnings, especially report mapping and attachment warnings.
Same commands	1	Required input, validation, authentication, file, Git, or API failure.
gate	0	Quality gate passed.
gate	1	Quality criteria failed. Commander also uses code 1 when a required gate option is omitted before the gate handler starts.
gate	2	Numeric validation, authentication, plan/run lookup, or API error after the gate handler starts.
--help, --version	0	Informational command completed.

Do not use tc report's exit code as the automated test verdict. The default is to preserve the test runner's exit code. tc gate is an opt-in alternative policy for workflows that deliberately use the complete TestCollab plan as the decision source.

Files written by the CLI

File	Written by	Content
tmp/tc_build	createBuild	TESTCOLLAB_BUILD_ID=<id>
tmp/tc_test_plan	createTestPlan and report	TESTCOLLAB_TEST_PLAN_ID=<id>
The --output path	getTestPlan	Formatted plan JSON. Its parent directory must already exist.

The tmp files are conveniences for later steps in the same workspace. Persist or export their values explicitly when your CI provider runs steps in isolated containers.