Skip to main content

LabScale CLI User Guide

Introduction

LabScale provides a client CLI tool that is intended to use in CI/CD automated pipeline. The the tool can trigger workflow jobs in the backend and wait or poll for job completion.

Download & Install

To download and install the LabScale CLI, do the following:

  1. Go to the LabScale website.

  2. Click on the Admin menu item in the left navigation pane. A list of administrator menu items should appear.

  3. Click on the CLI Keys menu item in the left navigation pane.

  4. Click on the CREATE A NEW KEY button. A dialog titled New Access Key will appear.

  5. Cut and paste the command line string into a terminal window to install and configure the CLI with the newly created key.

    danger

    Your CLI Access Key is only accessible on this screen. If you close the dialog or leave the page, you will not be able to copy the key again. If you lose your key, the only workaround is to create a new key.

Command Reference

The CLI is composed of several subcommands listed in the sections below. General usage:

./labscale-cli COMMAND [help|-h] [ARGS...]

config

The config subcommand will create or update the config and credential files used by the CLI. By default, the file is named cli-config.yaml and is located in the same folder as the tool. You cannot update an existing configuration without using the -force flag. Once configuration has been updated, any subcommand will automatically use that configuration by default.

tip

The teamId, clientId, brokerUrl, and token can also be provided as environment variables LABSCALE_TEAM_ID, LABSCALE_CLIENT_ID, LABSCALE_BROKER_URL, LABSCALE_SECRET_TOKEN respectively to any subcommand at run time.

  • Examples:

    • To create a new configuration file, or update the existing one:
    ./labscale-cli config -brokerUrl 'wss://broker.labscale.com:443/mqtt' -clientId 'myClientId' -teamId 'myTeamId' -token 'mySecretToken' -force
    • To show the current configuration:
    ./labscale-cli config -show

    BrokerURL: tls://broker.labscale.com:443
    TeamID: myTeamId
    ClientID: myClientId
    Username: myTeamId-myClientId
    AuthToken: *************
  • Usage:

    Usage of config:
    -brokerUrl string
    The broker URL (default "wss://broker.labscale.com:443/mqtt")
    -clientId string
    The client ID
    -code string
    The 'code' block provided by Labscale
    -config string
    Path to the cli-config.yaml (default "~/labscale-cli/cli-config.yaml")
    -force
    Force config updates.
    -teamId string
    The team ID
    -token string
    The authentication token

status

The status subcommand will return the status of the requested job ID as a JSON string and will exit with a non-zero status code on either an error with running the script, e.g. wait timeout, configuration error, missing job, etc., or an error occurred during the job's runtime, e.g. timeout or error.

Optionally, test failures over a certain number, or pass count under a certain number, can also result in a non-zero exit code. By default, a failure count greater than 1, or a pass count less than 1 will result with a non-zero exit status.

The status subcommand is intended for CI/CD services that need to poll on the status of remotely executed actions.

  • Examples:
    • To get the status of job ID 1:
    ./labscale-cli status -jobId 1
    {"jobID":1,"workfowID":"","status":"error","statusInfo":"exitcode: 1","requestor":"d0vpi4j23njg","stats":{"passed":0,"failed":0,"skipped":0},"startedAt":"2023-07-28T21:07:37.604429Z","endedAt":"2023-07-28T21:07:38.554429Z"}
    workflow error
  • Usage:
    Usage of status:
    -config string
    Path to the cli-config.yaml (default "~/labscale-cli/cli-config.yaml")
    -fail int
    Error if fail count more than value.
    -jobId int
    The job ID
    -pass int
    Error if pass count less than value. (default 1)
    -wait int
    Wait timeout for response (in seconds, 0 = infinite) (default 20)

trigger

The trigger subcommand will enqueue a workflow and, based on provided parameters, wait for either a response or a completion event. The subcommand will return the status of the requested Job ID as a JSON string and will exit with a non-zero status code on either an error with running the script, e.g. wait timeout, configuration error, etc., or an error occurred during the job's runtime, e.g. timeout or error.

Optionally, test failures over a certain number, or pass count under a certain number, can also result in a non-zero exit code. By default, a failure count greater than 1, or a pass count less than 1 will result with a non-zero exit status.

  • Examples:
    • To trigger a workflow and exit immediately after receiving the new job ID:
    ./labscale-cli trigger -releaseId 'xyz' -buildNumber '1' -deviceTypeId 'abcd' -poolId 'mypoolId' -workflowId 'myworkflowid'
    {"jobID":1,"workfowID":"myworkflowid","status":"queued","statusInfo":"","requestor":"a1b2c3","stats":{"passed":0,"failed":0,"skipped":0}}
    • To trigger a workflow and wait for completion:
    ./labscale-cli trigger -releaseId 'xyz' -buildNumber '2' -deviceTypeId 'abcd' -poolId 'mypoolId' -workflowId 'myworkflowid' -exitOnComplete
    {"jobID":2,"workfowID":"myworkflowid","status":"completed","statusInfo":"","requestor":"a1b2c3","stats":{"passed":1,"failed":0,"skipped":0},"startedAt":"2023-07-28T21:07:37.604429Z","endedAt":"2023-07-28T21:07:38.554429Z"}
  • Usage:
    Usage of trigger:
    -buildId string
    Build ID
    -buildNumber string
    Build number/version
    -buildUri string
    Location of the build
    -config string
    Path to the cli-config.yaml (default "~/labscale-cli/cli-config.yaml")
    -deviceId string
    The device ID. (Required when setting workflowId)
    -deviceTypeId string
    The device type ID (Required when setting workflowId)
    -exitOnComplete
    Wait for workflow completion.
    -fail int
    Error if fail count more than value.
    -jobsetID string
    The job set ID. (Mutually exclusive from workflowId)
    -metadata string
    Optional build metadata as a JSON string
    -pass int
    Error if pass count less than value. (default 1)
    -poolId string
    The pool ID. (Required when setting workflowId)
    -releaseId string
    Release ID
    -timeout int
    Workflow timeout in seconds (default 3600)
    -wait int
    Wait for response or completion event (in seconds, 0 = infinite)
    -workflowId string
    The workflow ID. (Mutually exclusive from jobsetId)

upload

The upload subcommand will upload a job package or test package to the LabScale account bucket and register it with the backend. The subcommand will return a JSON string containing the new Package ID, or an error string on error exiting with a non-zero status.

  • Example:
    • Upload a Test Package to Demo Project Release 1.0
    ./labscale-cli upload -projectId 1111bj7opryu -name MyExample -file ~/my_example.tgz
    {"statusCode":200,"requestorId":"ty8hpddkjmiq","location":"","filename":"my_example.tgz","contentLength":975,"contentEncoding":"utf-8","lastModified":"2024-03-04 14:04:29.211042315 -0800 PST","eTag":"\"c7cb10db4b37db811025bb5b75364952\"","name":"MyExample","type":"test","projectID":"1111bj7opryu","description":"A simple example","packageID":"xyz123","timeout":300}
  • Usage:
    Usage of upload:
    -config string
    Path to the cli-config.yaml (default "/tmp/labscale-cli/cli-config.yaml")
    -description string
    Description (optional)
    -file string
    The path to the file
    -name string
    The name of the package (optional)
    -projectId string
    Associated project ID
    -timeout int
    Package timeout in seconds (default 300)
    -type string
    The type of file, available types: [job test] (default "test")
    -wait int
    Wait for response or completion event (in seconds, 0 = infinite)

version

The version subcommand will print the version of the labscale-cli tool.

  • Example:
    • To display the current version of the CLI tool:
    ./labscale-cli version
    version: 1.0.0.0+wxyz