View a markdown version of this page

DLT CLI - Distributed Load Testing on AWS
Key capabilitiesInstallation and detailed referenceQuick start

DLT CLI

The DLT CLI lets you interact with the Distributed Load Testing on AWS REST API directly from your terminal. It enables scripted automation of load tests, allowing you to list, inspect, and start test scenarios and query run results as part of repeatable workflows.

The CLI targets the same IAM-authorized API Gateway as the DLT web console, so any operation available in the browser-based interface can also be performed from the command line using the same underlying API and permissions model.

The CLI source code and full documentation live in the solution’s GitHub repository under the source/cli directory. To find it, navigate to the Distributed Load Testing on AWS repository and open source/cli. The README.md in that directory is the authoritative reference for installation, configuration, authentication, and the complete command reference.

Key capabilities

Command group Description

configure

Configure the CLI with your DLT stack settings, either interactively or by importing an aws-exports.json file.

login

Authenticate with the DLT service and obtain the credentials needed to call the API.

logout

Remove stored credentials from the local machine.

token

Inspect and output authentication tokens and credential expiry status.

scenarios

List, view details, and start (re-run) existing test scenarios.

runs

Query test run results, view run details, compare against baselines, and download run artifacts.

The CLI supports three authentication modes: browser-based login (PKCE flow via the Cognito Hosted UI), headless SRP (Secure Remote Password) authentication, and direct IAM credential authentication. For full setup details on each mode, see the README.md in the source/cli directory of the GitHub repository.

Installation and detailed reference

The CLI is distributed as a portable Node.js bundle that can be run directly, or you can build it from source using the repository. To get started, navigate to the Distributed Load Testing on AWS repository on GitHub and open the source/cli directory. The README.md file in that directory contains:

  • Installation instructions (portable bundle and build-from-source)

  • Configuration and authentication setup for all three auth modes

  • Full command reference with usage examples

Quick start

Note

This quick-start assumes the DLT stack is already deployed.

The fastest way to get started is the portable bundle. This does not require cloning the repository or any build steps:

# Download the portable bundle
curl -sLo /usr/local/bin/dlt \
  https://raw.githubusercontent.com/aws-solutions/distributed-load-testing-on-aws/main/deployment/cli/dlt-cli.mjs

# Make it executable
chmod +x /usr/local/bin/dlt

# Point the CLI at your deployed DLT stack
dlt configure

# Authenticate with the DLT service
dlt login

# Run a command (for example, list test scenarios)
dlt scenarios list

Option 2: Build from source

If you prefer to build from source, clone the repository first. The project uses npm workspaces, so run the following commands from the repository root:

# Install all workspace dependencies
npm install

# Build the CLI
npm run build -w source/cli

# Link the dlt command into your PATH
npm link -w source/cli

# Point the CLI at your deployed DLT stack
dlt configure

# Authenticate with the DLT service
dlt login

# Run a command (for example, list test scenarios)
dlt scenarios list