Command-line interface

Install the Test Companion CLI and sign in, so you can generate, run, and fix tests from your terminal or CI pipeline.

The Test Companion CLI is a program you run in your terminal. Its command is tc. It runs the same AI agent as the Test Companion IDE extensions, with the same capabilities. You describe a task in plain language. The CLI then generates, runs, or fixes tests, drives a real browser or mobile device on BrowserStack, and reads and writes BrowserStack Test Management.

You can use tc in two ways. Run tc with no arguments to start an interactive chat session. Pass a prompt in quotes to run a single task and exit:

tc "write and run a login test for this app on Chrome"

The agent reads your code, writes the test, and runs it on BrowserStack. It prints the files it created, the browser and operating system it used, and a link to the build on the BrowserStack dashboard.

Prerequisites

Before you install the CLI, make sure you have the following:

• A BrowserStack account. If you do not have one, create a BrowserStack account.
• BrowserStack AI enabled for your account. To turn it on, go to AI preferences in your account settings. For the full procedure, see Activate BrowserStack AI.
• A macOS, Linux, or Windows computer with a terminal. A terminal is the app where you type commands. On macOS, open Terminal from Applications > Utilities. On Windows, open PowerShell from the Start menu.

The CLI runs on the following systems:

• macOS on Apple Silicon or Intel.
• Linux on x86-64 or ARM64, with glibc 2.28 or later. Ubuntu 20.04, RHEL 8, and Debian 10 and later releases meet this requirement.
• Windows on x86-64.

The installer includes everything tc needs to run. You do not need to install any other software first.

Install

Copy the command for your operating system, paste it into your terminal, and press Enter.

macOS and Linux

curl -fsSL https://test-companion.browserstack.com/cli/install.sh | sh

Windows

irm https://test-companion.browserstack.com/cli/install.ps1 | iex

When the installer finishes, it prints the folder where it placed tc. The default folder is ~/.local/bin.

Verify the install

In the same terminal, run the following command:

tc --version

The command prints test-companion CLI v<version>, where <version> is the installed release.

If the terminal reports that tc is not found, the install folder is not on your PATH. Your PATH is the list of folders your terminal searches for commands. Add the folder that the installer printed to your PATH, or ask your IT team to add it.

To install in a different folder, set the TC_INSTALL_DIR environment variable to that folder before you run the installer.

Pin or roll back to a specific version

Every release stays available at a permanent address. To install an exact version, pass the version and the checksum of that release:

tc upgrade --version <version> --sha256 <sha256>

Replace <version> with the release number and <sha256> with the SHA-256 checksum of that release. If you omit the checksum, the installer skips checksum verification and prints a warning.

Sign in

The tc command runs against your BrowserStack account. You sign in one time. The CLI stores your credentials on your computer and reuses them across sessions.

Sign in with a browser

In your terminal, run the following command:

tc auth login

Your browser opens a BrowserStack page that asks you to allow access. After you allow it, return to the terminal. The tc command stores your sign-in tokens. On a computer with no browser, such as an SSH session, the command prints the sign-in URL instead. Open that URL in a browser on another device.

To check that you are signed in, run tc auth whoami. The command prints the account you signed in with.

Sign in without a browser

Use this method in a continuous integration (CI) pipeline or on a computer with no browser. The tc command exchanges your BrowserStack username and access key for tokens. Find both values on the Account and profile page.

# Pass the credentials as flags
tc auth login --username "YOUR_USERNAME" --access-key "YOUR_ACCESS_KEY"

# Or set the environment variables and run the command without flags
export BROWSERSTACK_USERNAME="YOUR_USERNAME"
export BROWSERSTACK_ACCESS_KEY="YOUR_ACCESS_KEY"
tc auth login

Replace YOUR_USERNAME and YOUR_ACCESS_KEY with your BrowserStack username and access key.

The following commands manage your sign-in:

Run your first task

The agent works on the project in your current folder. To run your first task, follow these steps:

1. In your terminal, navigate to the project folder you want to test, then run tc to start an interactive session.
2. Type a request in plain language, such as generate test cases for the login flow, and press Enter.
3. When the agent asks to run a command or edit a file, choose Approve to let it continue.
4. Read the result. The agent prints what it created and, for a test run, a link to the build on BrowserStack.
5. Type /exit to leave the session.

To run the same request as a single task instead, put it in quotes: tc "generate test cases for the login flow". To pick up a past session later, run tc history list to find it, then tc resume <task-id>.

Common commands

The following commands cover most day-to-day use:

Usage and limits

The beta applies usage limits. To see how many AI credits you have used against your plan or group allowance, run tc usage. Inside a session, type /usage to see the same information for the current session.

Get help

• Run tc <command> --help to see the flags of any command.
• Inside a session, type /help to list the slash commands.
• Run tc report-bug "<description>" to send a bug report to the Test Companion team.
• Run tc feedback to rate a session and leave a comment.

Next steps

• Run tasks with the CLI: Run one-shot and interactive tasks, and work in the interactive session.
• CLI command reference: Look up every tc command.
• CLI configuration and troubleshooting: Configure tc, branch on exit codes in CI, and fix common problems.