Join our Discord
CLI configuration and troubleshooting
Configure the Test Companion CLI, branch on its exit codes in CI, find the files and environment variables it uses, and fix common problems.
This page covers the settings tc stores, the exit codes it returns, the files and environment variables it reads, and fixes for common problems.
Configuration
The tc config command reads and writes a small set of settings. Run the commands in your terminal. A change takes effect on your next run.
tc config list # Show every key and its current value
tc config get chat.mode # Print one value
tc config set chat.mode plan # Change a value
The following keys are available:
| Key | Values | Default | Description |
|---|---|---|---|
chat.preferred_language |
Any language | English | Language the agent replies in. |
chat.mode |
act or plan
|
act |
In act mode, the agent works autonomously. In plan mode, it writes a plan and waits for your approval. |
chat.test_case_type |
def or bdd
|
def |
Format of generated test cases. def produces step-based cases. bdd produces Gherkin cases with Given, When, and Then steps. If your Test Management tool cannot store BDD cases, tc falls back to def. |
custom_instructions |
Free text | None | Extra instructions added to the start of every task. |
browser.viewport |
<width>x<height> |
1280x800 |
Viewport size of the local browser. |
browser.headless |
true or false
|
false |
Launch the local browser without a visible window. |
checkpoints |
true or false
|
true |
Take workspace snapshots during a task. |
max_steps |
Integer, 0 or higher | 0 |
Maximum number of agent turns per task. 0 means no limit. When the cap is reached, the run ends with a step limit reached result. |
timeout_minutes |
Integer, 0 or higher | 0 |
Maximum minutes per task, checked between turns. 0 means no limit. A tool call that is already running is never interrupted. |
Four settings live elsewhere. You cannot choose the AI model. Approvals are set per run with the --yolo and --auto-approve flags. Debug mode is set per run with the TC_DEBUG=1 environment variable. Telemetry is turned on or off with tc config telemetry on or tc config telemetry off. If you try to set one of these with tc config set, the command tells you where to set it instead.
Exit codes
An exit code is a number that tc returns when it finishes. You need these codes only when a script or a continuous integration (CI) pipeline runs tc for you. The code tells the pipeline whether the run passed, a test failed, or the run was blocked. Branch on the following codes:
| Code | Meaning |
|---|---|
0 |
Success. |
1 |
Any unclassified error. |
2 |
Invalid flags or usage. |
3 |
Not signed in. Run tc auth login. |
4 |
The run started, but the agent hit a fatal error. |
5 |
The agent finished, but the test it wrote or fixed did not pass. |
6 |
A blocking question went unanswered under --yolo. |
7 |
The turn completed, but the agent could not perform the requested task. |
Files
The CLI stores everything under ~/.testcompanion/. The ~ stands for your home folder. The following paths are relative to that folder:
| Path | Contents |
|---|---|
data/secrets.json |
Your BrowserStack tokens, stored as plain text that only your user account can read. |
data/config.json |
Settings that tc manages for you. |
data/globalState.json |
Your tc config settings. |
data/checkpoints/ |
Workspace snapshots, one set per task. |
logs/<cmd>-<timestamp>.log |
A local trace of every session. |
Environment variables
| Variable | Purpose |
|---|---|
BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY
|
Sign in without a browser with tc auth login. Set them to your BrowserStack username and access key. |
TC_CLI_YOLO |
Never pause for questions or approvals. The --yolo and --json flags set this variable automatically. |
TC_DEBUG=1 |
Enable debug mode for a run. |
TC_INSTALL_DIR |
Directory where the installer places the tc wrapper. The default is ~/.local/bin. |
TC_VERSION and TC_SHA256
|
Pin the installer to an exact version and its checksum. Without TC_SHA256, the installer skips checksum verification and prints a warning. |
Troubleshooting
The following table lists common symptoms and their fixes:
| Symptom | Fix |
|---|---|
not signed in with exit code 3 |
Run tc auth login and sign in again. In CI, set BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY first. |
Killed: 9 on macOS after you copy the tc program to another location |
A copied program loses its security signature. Run the official installer again. It signs the program again. |
| A run seems stuck | Run the command again with -v added, then open the newest file in ~/.testcompanion/logs/ and look for the last message. |
connection refused on the first run |
Run the command again. If the error persists, run it with -v added and check the newest file in ~/.testcompanion/logs/. |
tc mcp is missing |
Model Context Protocol (MCP) is not enabled for your account yet. There is no local override. |
| You need a command’s flags | Run tc <command> --help. |
For any other problem, run tc report-bug "<description>" to send a report to the Test Companion team. To rate a session, run tc feedback.
Next steps
-
CLI command reference: Look up every
tccommand. - Run tasks with the CLI: Run one-shot and interactive tasks.
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
Thank you for your valuable feedback!