# Loadster Command Line Interface > The Loadster CLI lets you launch load tests and check results from the command line, enabling CI/CD integration with Jenkins, GitHub Actions, and more. Source: https://loadster.com/manual/loadster-cli/ Loadster is primarily a browser-based tool, but you can use the Loadster CLI to play local scripts and start and run load tests from the command line. If your scripts exist on your local filesystem as plain old .js files, you can play them with the Loadster CLI. You can even use them in load tests. The script results and test reports will be available in Loadster. ## Installing the Loadster CLI The open source [Loadster CLI](https://github.com/loadster/loadster-cli) is available as a self-contained native binary for Windows, Mac, and Linux. [Download the Loadster CLI for Windows, Mac, or Linux](https://github.com/loadster/loadster-cli/releases) You can store the binary anywhere on your system you want, as long as it's in your PATH. ## Logging In with the Loadster CLI After you install the Loadster CLI, you can use it to log in to your Loadster account. This basically obtains an auth token for the CLI to use, and the CLI stores it locally in a configuration file so it can communicate with the Loadster API. ```bash $ loadster login Loadster Username: example@example.com Loadster Password: ******** ``` If you're on a shared or untrusted machine and need to remove the local auth token, you can log out afterwards. ```bash $ loadster logout ``` Otherwise, the CLI maintains a session for quite some time. ## Selecting a Project with the Loadster CLI Most CLI operations, like playing a script or running a load test, require that you're working in a specific Loadster project. You can list projects and select one to use. ```bash $ loadster projects list $ loadster projects use a83sf61 ``` Once you're "using" a project, script runs and test reports you create from the command line will be stored in that project. You can change to a different project at any time. ## Playing Scripts with the Loadster CLI The Loadster CLI can play scripts that already exist in your Loadster project. It can also play local .js files as Loadster scripts. If you want to play a script that already exists in your Loadster project (one that you can see and edit from your dashboard within the current project) you can specify its ID. ```text $ loadster play s63fa11 ``` If you want to play a local protocol script that doesn't exist in your Loadster dashboard, you can point it at the local file. ```text $ loadster play --file ./examples/my-protocol-script.js ``` Playing a local browser script is similar, but you'll have to specify a bot type in order for the bot to be equipped with a web browser. ```text $ loadster play --file ./examples/my-browser-script.js --type=browser ``` When you play a local script, Loadster basically treats the entire file as a [code block](https://loadster.com/manual/code-blocks/), so you can use all the special objects available in a code block in your local script. The CLI blocks while the script runs, and prints realtime script logs like you'd see when playing from the dashboard. It also gives you a link to view the full script run in your browser, in case you want to view screenshots or debug your script further. ## Running Tests with the Loadster CLI The [Loadster CLI](https://github.com/loadster/loadster-cli) has two modes for running load tests. If you `start` a test, the CLI simply launches the test and exits, providing you with links to view the test report or realtime progress. If you `run` a test, the CLI blocks while the test runs, optionally evaluating assertions to pass or fail the load test based on key metrics. ### Load Testing with a Scenario Trigger Code To run a test from a scenario that you've created on your Loadster dashboard, you'll need the scenario's **trigger code**. You can get this trigger code by expanding the big launch button on the scenario screen. You can then start a test by referencing the trigger code. ```text $ loadster start WsHDupkZEYkSD7bT ``` Similarly, you can run a test and wait for it to finish with `run` instead of `start`. ```text $ loadster run WsHDupkZEYkSD7bT ``` Testing with a trigger code is the easiest way to run a scenario that you've previously created in your Loadster project. ### Load Testing with a Local Script File If your script files exist on your local filesystem instead of in your Loadster dashboard, you can still use them for load testing. To do this, you'll need to specify all the load test options from the command line. ```text $ loadster start --script=./my-browser-script \ --type=browser \ --bots=100 \ --location="Europe - London" \ --ramp-up-minutes=3 \ --ramp-up-pattern=aggressive \ --peak-minutes=3 \ --ramp-down-minutes=3 \ --ramp-down-pattern=linear ``` Again, you can substitute `run` for `start` if you want the Loadster CLI to block and wait until the test finishes. ### Generating JSON Output If you want the CLI to print JSON values instead of human-readable text, you can add the `--json` flag. This might be helpful if you're integrating the CLI into your own CI tool or interpreting the test results from a cron job or something. ```text $ loadster run WsHDupkZEYkSD7bT --json ``` ### Labeling the Test Sometimes it's helpful to tie a load test back to a specific build number or configuration. You can do this with the `--label` switch. ```text $ loadster run WsHDupkZEYkSD7bT --label=ci-build-238-beta ``` Afterwards, this label will show up on the test report and in your activity feed, so you can easily reference load test results back to the relevant build. ### Blocking and Observing Test Status If you want the CLI to block until the test finishes instead of exiting immediately after starting the test, use the `run` command instead. ```text $ loadster run WsHDupkZEYkSD7bT # text output $ loadster run WsHDupkZEYkSD7bT --json # json output ``` When you use the `run` command (instead of the `start` command), the CLI will keep watching the test progress, and print useful stats every few seconds. For example: ```text [0:03:25] - runningUsers: 175.00 - responseTimeAverage: 0.25 - responseTimeP90: 0.71 - uploadThroughputBytesPerSecond: 2437.50 - downloadThroughputBytesPerSecond: 190337.25 - pagesPerSecond: 11.08 - hitsPerSecond: 32.17 - totalPages: 2660.00 - totalHits: 11320.00 - totalErrors: 1.00 - totalIterations: 156.00 ``` When the load test finishes, the CLI will exit. ### Assertions The Loadster CLI also supports assertions, so you can evaluate high-level test result metrics against pass-fail criteria. This is useful for automatically failing a build if the performance test results aren't inline with expectations. ```text $ loadster run WsHDupkZEYkSD7bT --assert 'totalErrors == 0' --assert 'avgHitsPerSecond >= 24.5' ``` The example above makes two assertions: the total number of errors in the test must be equal to zero, and the average hits per second throughout the test must be more than 24.5. Assertions are not required, but you can use pretty much as many as you want. Assertions work on the following metrics: * `maxUsers` * `avgBytesPerSecond` * `maxBytesPerSecond` * `avgPagesPerSecond` * `maxPagesPerSecond` * `avgHitsPerSecond` * `maxHitsPerSecond` * `totalBytesTransferred` * `totalPages` * `totalHits` * `totalErrors` * `totalIterations` The following operators are supported in assertions: * `==` * `<=` * `>=` * `<` * `>` At the end of the test, a breakdown of which assertions passed/failed is printed. If any assertions failed, the process exits with a non-zero status code. ## Getting Help with the Loadster CLI If you're having trouble with the Loadster CLI, please get in touch! We're happy to provide support. You can also check out the [Loadster CLI](https://github.com/loadster/loadster-cli) project on GitHub... it's open source and we welcome contributions.