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:
-
Go to the LabScale website.
-
Click on the Admin menu item in the left navigation pane. A list of administrator menu items should appear.
-
Click on the CLI Keys menu item in the left navigation pane.
-
Click on the CREATE A NEW KEY button. A dialog titled New Access Key will appear.
-
Cut and paste the command line string into a terminal window to install and configure the CLI with the newly created key.
dangerYour 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.
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