Tosca CLI

Tosca CLI is a command-line tool for Tosca Cloud that lets you perform the following actions via terminal or CI pipeline:

• Manage workspaces

• Run playlists

Tosca CLI is available to Tricentis users enrolled in the Tricentis Labs program (opens in new tab).

Install Tosca CLI

To install Tosca CLI, select Downloads in Tosca Cloud and download the package for your operating system.

After you complete the installation steps for your operating system, run the following command to verify that Tosca CLI is installed correctly.

toscactl --version

Sign in

To authenticate with Tosca Cloud, run the following command.

toscactl login

A browser window opens for authentication. Tosca CLI stores your session locally, so you don't need to sign in again for subsequent commands.

Set a workspace

If you work mainly in one workspace, set it as your active workspace. Tosca CLI uses it automatically for all subsequent commands.

toscactl workspace set <WorkspaceName>

Replace <WorkspaceName> with the name of your workspace.

If your CI/CD pipelines target a different workspace with each run, pass the --workspace option to override the active workspace for that command only.

toscactl <command> --workspace <WorkspaceName>

Replace <command> with the Tosca CLI command to run, and <WorkspaceName> with the name of the workspace.

Run a playlist

Use --help on any command to get context-specific help, including its available options.

$ toscactl playlists run --help
Manage playlist runs

Usage: toscactl playlists run [OPTIONS] <COMMAND>

Commands:
  start  Start a new playlist run
  view   View details of a playlist run
  help   Print this message or the help of the given subcommand(s)

Options:
  -s, --silent                 Suppress all output except results
      --json                   Output results as JSON instead of table
      --workspace <WORKSPACE>  Override the active workspace for this command (name or id); not persisted
  -h, --help                   Print help

You can also use --help on a specific subcommand to see just its options.

$ toscactl playlists run start --help
Start a new playlist run

Usage: toscactl playlists run start [OPTIONS] <NAME_OR_ID>

Arguments:
  <NAME_OR_ID>
          Playlist name or ID (UUID)

Options:
      --private
          Run as private execution

  -s, --silent
          Suppress all output except results

      --json
          Output results as JSON instead of table

      --param <KEY=VALUE>
          Parameter override in key=value format (repeatable)

      --wait
          Block until the run completes, showing live progress

      --workspace <WORKSPACE>
          Override the active workspace for this command (name or id); not persisted

      --assert-success
          Exit non-zero if the run does not reach the "succeeded" state. Requires --wait

      --retry <N>
          Retry up to N times when there are failing tests. Implies --wait

          [default: 0]

      --report <REPORT>
          Report format to write after the run completes. Implies --wait. Requires --report-path

          Possible values:
          - junit: JUnit XML report

      --report-path <REPORT_PATH>
          Output path for the report (used with --report)

  -h, --help
          Print help (see a summary with '-h')

In a CI pipeline, you often need to wait for a playlist run to finish and know right away if it failed. Combine the following options to do that:

• --wait waits for the run to finish and shows live progress.

• --assert-success makes the command fail if the run doesn't succeed.

• --workspace runs the playlist in a specific workspace, just for this command.

In this example, you run "my playlist" in the workspace "my workspace" and wait for the result. The --workspace option is optional here. If you already Set a workspace, you only need it to target a different one for this run.

toscactl playlists run start --wait --assert-success --workspace "my workspace" "my playlist"

What's next

Use toscactl to run playlists from your terminal.