Skip to content

SolaceLabs/solace-tryme-cli

Repository files navigation

Contributor Covenant

Solace Try-Me CLI


The Solace Try-Me CLI is a command line tool used to publish and receive messages from the Solace PubSub+ Broker. Designed to help develop, test and debug Solace PubSub+ services and applications faster without the need to use a graphical interface.

Documentation

Installation

MacOS using Homebrew

brew tap SolaceLabs/stm
brew install stm

Linux (or WSL on Windows) using apt-get

Run the following commands to add the SolaceLabs repo to APT

echo "deb [arch=amd64 trusted=yes] https://raw.githubusercontent.com/SolaceLabs/apt-stm/master stm main" | sudo tee  /etc/apt/sources.list.d/solace-stm-test.list

Install the latest version of stm

sudo apt-get update
sudo apt-get install stm

Download the Archive

For manual installation of the tool directly from archives, navigate to Git Releases, locate the latest release and review the zip files (approprietly named with the target OS name) under Assets. Download the right bundle based on your OS and extract the binary/executable. Move the binary/executable file to a folder that is in the PATH or update the path to contain the folder where the file is present.

For Windows For Linux For Mac
You will find an extracted binary stm.exe and is ready for use.

Make sure that either the binary file is copied over to a directory that is in the %PATH% or the %PATH% is updated with the directory where the binary is present.

Note that the configuration files created by stm will be stored in %USERPROFILE%\.stm folder by default.

NOTE: If you want to use a different directory for storing stm artifacts, set the environment variable STM_HOME pointing to the full path of the desired folder.
set STM_HOME = <new_folder_full_path>
You will find an extracted binary stm and is ready for use.

Make sure that either the binary file is copied over to a directory that is in the $PATH or the $PATH is updated with the directory where the binary is present.

Note that the configuration files created by stm will be stored in $HOME/.stm (or ~/.stm) folder by default.

NOTE: If you want to use a different directory for storing stm artifacts, set the environment variable STM_HOME pointing to the full path of the desired folder.
export STM_HOME = <new_folder_full_path>
You will find an extracted binary stm.

MacOS would complain that the executable is from an unidentified developer, run the following command to fix this.

xattr -dr com.apple.quarantine stm

Make sure that either the binary file is copied over to a directory that is in the $PATH or the $PATH is updated with the directory where the binary is present.

Please note that the configuration files created by stm will be stored in $HOME/.stm (or ~/.stm) folder by default.

NOTE: If you want to use a different directory for storing stm artifacts, set the environment variable STM_HOME pointing to the full path of the desired folder.
export STM_HOME = <new_folder_full_path>

Verify Installation

Run the version command stm -v to ensure that you have downloaded the latest release.

$ stm -v
█████╗ █████╗ ██╗    ████╗  ████╗████╗  ████████╗█████╗ ██╗   ██╗    ███╗  ███╗█████╗
█╔═══╝██╔══██╗██║   ██╔═██╗██╔══╝██══╝  ╚══██╔══╝██╔═██╗╚██╗ ██╔╝    ████╗ ███║██╔══╝
█████╗██║  ██║██║   ██████║██║   ███╗      ██║   █████╔╝ ╚████╔╝     ██╔███╔██║███╗
╚══██║██║  ██║██║   ██╔═██║██║   ██╔╝      ██║   ██╔═██╗  ╚██╔╝ ███  ██║╚██╝██║██╔╝
█████║╚█████╔╝█████╗██║ ██║╚████╗████╗     ██║   ██║ ██║   ██║       ██║ ╚╝ ██║█████╗
╚════╝ ╚════╝ ╚════╝╚═╝ ╚═╝ ╚═══╝╚═══╝     ╚═╝   ╚═╝ ╚═╝   ╚═╝       ╚═╝    ╚═╝╚════╝

<version_goes_here>

NOTE: The version number should match the stm version you downloaded.

Command Structure

The following view captures the command hierarchy of the stm cli tool.


stm
├── -v, --version                   /* output the version number                      */
├── -h, --help                      /* display help for command                       */
├── -he, --help-examples            /* display examples                               */
├── send                            /* execute a send command                         */
├── receive                         /* execute a receive command                      */
├── request                         /* execute a request command                      */
├── reply                           /* execute a reply command                        */
├── config                          /* manage command configurations                  */
│   ├── -h, --help                  /* display help for command                       */
│   ├── -he, --help-examples        /* display examples                               */
│   ├── init                        /* initialize command configuration               */
│   ├── list                        /* list command configurations                    */
│   └── delete                      /* delete command configuratio                    */
└── manage                          /* manage connection and resources                */
│   └── -h, --help                  /* display help for command                       */
│   ├── -he, --help-examples        /* display examples                               */
│   ├── connection                  /* manage VPN connection                          */
│   ├── semp-connection             /* manage VPN SEMP connection                     */
│   ├── queue                       /* manage queue                                   */
│   ├── client-profile              /* manage client-profile                          */
│   ├── acl-profile                 /* manage acl-profile                             */
│   └── client-username             /* manage client-username                         */
└── feed                            /* manage event feeds                             */
    ├── -h, --help                  /* display help for command                       */
    ├── -he, --help-examples        /* display examples                               */
    ├── preview                     /* Validate and preview an AsyncAPI document      */
    ├── generate                    /* Generate event feed from an AsyncAPI document  */
    ├── configure                   /* Configure event feed rules                     */
    ├── run                         /* Run event feed                                 */
    ├── list                        /* List event feeds                               */
    ├── copy                        /* Duplicate a community event feed locally       */
    └── contribute                  /* Contribute to community event feeds            */

Command Parameters

For details on CLI parameters, refer to the parameters guide.

You can also use:

  • -h or --help option on the command to see basic parameters.
  • -hm or --help-more option on the command to see other (advanced) parameters.

Command Examples

Refer to the examples guide for sample commands.

You can use:

  • -he or --help-examples option on the command to see corresponding examples.

Command Persistence

The stm utility supports persisting command settings to a file, that can be referenced by name. In fact, the default configuration file present is populated with messaging and manage comments with default settings.

To know more about configuration file and how to create and manage commands, refer to configuration guide.

Setup stm configuration

Use with a Software Broker

A software broker installation exposes certain default settings out of the box for messaging and management.

Messaging: Broker URL for websocket connection (localhost and port 8008), message VPN (default), client username (default) and password (default).

Management: Broker SEMP URL (localhost and 8080), message VPN (default), semp username (admin) and semp password (admin).

Taking advantage of this, the stm tool will automatically create a default configuration when an stm command is run without any config reference. You can review the sample configuration for more details on the settings.

  1. Initialize configuration
stm config init
✔  success   success: initialized configuration with default command settings on 'stm-cli-configuration.json' successfully
Broker Connection Broker SEMP Connection
Broker URL: ws://localhost:8008 Broker SEMP URL: http://localhost:8080/SEMP/v2/config
VPN Name: default VPN Name: default
Username: default SEMP Username: admin
Password: default SEMP Password: admin
  1. If you want to update the settings, you can use the stm manage command.
stm manage connection --url ws://localhost:8008 --vpn default --username default --password default
ℹ  info      info: loading 'connection' command from configuration 'stm-cli-config.json'
ℹ  info      info: loading configuration 'stm-cli-config.json'
ℹ  info      info: checking settings for operation - connection
✔  success   success: updated command settings 'connection' on configuration file 'stm-cli-config.json' successfully

To update SEMP connection for managing queue, acl-profile, client-profile and client-username:

stm manage semp-connection --semp-url http://localhost:8080/SEMP/v2/config --semp-vpn default --semp-username admin --semp-password admin
ℹ  info      info: loading 'sempconnection' command from configuration 'stm-cli-config.json'
ℹ  info      info: loading configuration 'stm-cli-config.json'
ℹ  info      info: checking settings for operation - sempconnection
✔  success   success: updated command settings 'sempconnection' on configuration file 'stm-cli-config.json' successfully

NOTE: If you want to create additional configuration for a different broker, you can create new configuration by executing the above command with an additional parameter of --config <CONFIG_NAME>, and you can refer to the named configuration by specifying them in any of the messaging and management commands.

Use with a Cloud Broker

Unlike Software Broker, a Cloud Broker requires explicit initialization as the parameters vary from instance to instance.

Before proceeding, collect information on the following settings from the “Connect” and “Manage” tabs for your Messaging Service in Solace Cloud.

Broker Connection
(from Connect → “Solace Web Messaging”)
Broker SEMP Connection
(from Manage → “SEMP - REST API”)
URL URL
VPN Name VPN Name
Username Username
Password Password

  1. Initialize Configuration
stm config init
✔  success   success: initialized configuration with default command settings on 'stm-cli-configuration.json' successfully
  1. Now, update broker messaging and SEMP connection

To update broker connection settings for messaging commands, you can issue the following command to update the configuration.

stm manage connection --url wss://mr-connection-xxxx.messaging.solace.cloud:443 --vpn my-broker --username solace-cloud-client --password xxxxx
ℹ  info      info: loading 'connection' command from configuration 'stm-cli-configuration.json'
ℹ  info      info: loading configuration 'cloud-broker'
ℹ  info      info: checking settings for operation - connection
ℹ  info      info: [1] url of connection changed: ws://localhost:8008 => wss://mr-connection-xxxx.messaging.solace.cloud:443
ℹ  info      info: [2] vpn of connection changed: default => my-broker
ℹ  info      info: [3] username of connection changed: default => solace-cloud-client
ℹ  info      info: [4] password of connection changed: default => xxxxx
⚠  warning   warn: VPN Connection settings changed, this would impact all the messaging commands on the configuration
Changes detected in the settings, do you want to overwrite (y/n): y
✔  success   success: updated command settings 'connection' on configuration file 'stm-cli-configuration.json' successfully

To update SEMP connection for managing queue, acl-profile, client-profile and client-username:

stm manage semp-connection --semp-url https://mr-connection-xxxx.messaging.solace.cloud:943/SEMP/v2/config --semp-vpn my-broker --semp-username xxx-admin --semp-password xxxxx
ℹ  info      info: loading 'sempconnection' command from configuration 'cloud-broker'
ℹ  info      info: loading configuration 'stm-cli-configuration'
ℹ  info      info: checking settings for operation - sempconnection
ℹ  info      info: [1] sempUrl of sempconnection changed: http://localhost:8080 => https://mr-connection-xxxx.messaging.solace.cloud:943/semp/v2/config
ℹ  info      info: [2] sempVpn of sempconnection changed: default => my-broker
ℹ  info      info: [3] sempUsername of sempconnection changed: admin => xxx-admin
ℹ  info      info: [4] sempPassword of sempconnection changed: admin => xxxxx
⚠  warning   warn: VPN SEMP Connection settings changed, this would impact all the management commands on the configuration
Changes detected in the settings, do you want to overwrite (y/n): y
✔  success   success: updated command settings 'sempconnection' on configuration file 'stm-cli-configuration.json' successfully

NOTE: If you want to create additional configuration for a different broker, you can create new configuration by executing the above command with an additional parameter of --config <CONFIG_NAME>, and you can refer to the named configuration by specifying them in any of the messaging and management commands.

Run stm tool

Working with Software Broker

Once you complete the stm setup process and a configuration is successfully created, you can run the messaging commands.

Receive Messages

stm receive
ℹ  info: loading configuration 'stm-cli-config.json'
…  connecting to broker [ws://localhost:8008, vpn: default, username: default, password: ******]
✔  success: === stm_recv_b1485ead successfully connected and ready to receive events. ===
ℹ  info: subscribing to solace/try/me
ℹ  info: press Ctrl-C to exit
✔  success: successfully subscribed to topic: solace/try/me

On a second window/terminal, you can launch a publisher and see the events received on the receiver.

stm send
ℹ  info: loading 'send' command from configuration 'stm-cli-config.json'
…  connecting to broker [ws://localhost:8008, vpn: default, username: default, password: ******]
✔  success: === stm_pub_0d68a409 successfully connected and ready to publish events. ===
…  publishing...
✔  success: message published to topic - [Topic solace/try/me], type - BINARY
ℹ  info: Message Properties
Destination:                            [Topic solace/try/me]
ℹ  info: Message Payload (bytes): 101
✔  success: disconnecting from Solace PubSub+ Event Broker...
✔  success: disconnected
✔  success: exiting...

At this point, you should see the event received on the receiver.

✔  success: message Received - [Topic solace/try/me], type - BINARY
ℹ  info: Message Properties
Destination:                            [Topic solace/try/me]
ℹ  info: Message Payload (bytes): 100

NOTE: stm supports a default output mode that prints the destination and the message payload length (not the payload itself). However, if you want more details around message & user properties and payload - explore the other options i.e., PROPS to print message properties + just payload length, and FULL to print message properties and a pretty-print of the payload.

Working with Cloud Broker

Since the connection parameters are distinct for Cloud Broker, you will have to create a new Try-Me CLI configuration with appropriate connection parameters. You can make the stm operations directed to a specific broker by specifying the configuration that holds that broker's connection details by specifying --config <CONFIG_FILE> parameter.

At this point, the functionality of messaging commands are same irrespective of local or cloud broker. Try stm send and stm receive commands with a configuration containing cloud broker.

🎉 You are set, explore other commands like request, reply and the parameters that goes along with the messaging commands!

Using stm to create and modify Broker resources

stm supports creation and management of key broker resources relevant to messaging operations, like:

  • Client Profile
  • ACL Profile
  • Client Username and
  • Queue

Create a Queue

The default stm configuration has a default a queue create command - explore the manage -> queue setting in the sample configuration file.

You can simply run the command by

stm manage queue 
ℹ  info: loading 'queue' command from configuration 'stm-cli-config.json'
✔  success: queue 'stm-queue' created successfully
✔  success: subscription to topic 'solace/try/me' added successfully
✔  success: 1 subscription(s) found on queue stm-queue -
solace/try/me
✔  success: exiting...

Of course, if you want to specify queue parameters refer to the parameters of the stm queue command and set them appropriately.

Checkout examples of the command by passing -he or --help-examples parameter.

stm manage queue -he
ℹ  info: loading 'queue' command from configuration 'stm-cli-config.json'

Examples:
// execute the default queue command with settings defined on the
// default configuration 'stm-cli-config.json'
stm manage queue

HINT: You can view the default queue command settings 'stm config list --name queue'!

NOTE: The actual operation is determined by the operation parameter - create, update or delete!

// execute a specific queue command from the named configuration
stm manage queue --config cloud-broker --name queue

// execute the default queue command with settings defined on the default
// configuration 'stm-cli-config.json', but with command-line overrides
stm manage queue --update --add-subscriptions solace/try/me "stm/logistics/>"

NOTE: You can override any of the queue parameters
that are applied only for this instance of execution!

// If you want to run a queue entirely based on the command-line parameters
// without any reference to recorded command settings, you can do so by specifying
// requisite parameters in the command-line

stm manage queue --create my-queue --semp-url http://localhost:8080/SEMP/v2/config --semp-vpn default --semp-username admin --semp-password admin --add-subscriptions  stm/cli/topic --list-subscriptions

....

Refer to the examples guide for more details.

Using stm feed tool for event feed generation

The stm feed tool helps you transform Applications designed in Solace Event Portal into event feeds for streaming events to a broker. It also supports publicly available REST API endpoints and convert them into event feeds by invoking the APIs to generate events.

stm feed allows you to preview and generate an event feed from an AsyncAPI document. The tool's primary purpose is to help you quickly set up an event feed on your local machine, configure data generation rules, and use it. Additionally, you can contribute your feed for community use by following the contribution process (referred to as community or contributed feeds available on the Community Event Feeds site).

A quick overview of the supported commands:

preview - Preview an AsyncAPI document or a local or community feed generate - Generate an event feed from an AsyncAPI document or a REST API configure - Configure event feed rules (mock data and publish rules) list - List available event feeds (local and community feeds) run - Run an event feed locally to stream events to a local or cloud broker copy - Copy/Clone a community feed to local stm feeds to customize/run locally contribute - Contribute your local feed for community consumption (publish to the community feeds site)

For more details, please review the EVENT FEEDS documentation.

Contributing

Contributions are encouraged! Please read CONTRIBUTING.md for details on our CODE_OF_CONDUCT.md, and the process for submitting pull requests to us.

Develop

Recommended version for Node environment:

  • v18.*.*
# Clone
git clone --recurse-submodules git@github.com:SolaceLabs/solace-tryme-cli.git
cd solace-tryme-cli

# Install dependencies
yarn install

# Compiles and hot-reloads for development
yarn run dev

# Compiles and minifies for production
yarn run build

# Creates packages for target platforms
yarn run package

# Optional: To get the latest changes from the feeds site repo: 
git submodule update --remote

After a successful build, you will see the binary executable for each system in the release directory.

Run from build

After running yarn install above you can now run from the build using yarn run index [command]

$ yarn run index

Usage: stm [options] [command]

A Solace Try-Me client for the command line

Options:
  -v, --version         output the version number
  -he, --help-examples  show cli command examples
  -h, --help            display help for command

Commands:
  send [options]        Execute a send command
  receive [options]     Execute a receive command
  request [options]     Execute a request command
  reply [options]       Execute a reply command
  config [options]      Manage command configurations
  manage [options]      Manage broker connection and resources
  

Technology Stack

Resources

This is not an officially supported Solace product.

For more information try these resources:

Authors

See the list of contributors who participated in this project.

License

See the LICENSE file for details.