@solace-community/stm
v0.0.49
Published
Solace Try-Me Command Line Tool
Downloads
292
Readme
Solace Try-Me CLI
Solace Try-Me CLI is a CLI Client on the command line to publish and receive messages from 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
Quick Start
Go 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 stmMake 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
█████╗ █████╗ ██╗ ████╗ ████╗████╗ ████████╗█████╗ ██╗ ██╗ ███╗ ███╗█████╗
█╔═══╝██╔══██╗██║ ██╔═██╗██╔══╝██══╝ ╚══██╔══╝██╔═██╗╚██╗ ██╔╝ ████╗ ███║██╔══╝
█████╗██║ ██║██║ ██████║██║ ███╗ ██║ █████╔╝ ╚████╔╝ ██╔███╔██║███╗
╚══██║██║ ██║██║ ██╔═██║██║ ██╔╝ ██║ ██╔═██╗ ╚██╔╝ ███ ██║╚██╝██║██╔╝
█████║╚█████╔╝█████╗██║ ██║╚████╗████╗ ██║ ██║ ██║ ██║ ██║ ╚╝ ██║█████╗
╚════╝ ╚════╝ ╚════╝╚═╝ ╚═╝ ╚═══╝╚═══╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝╚════╝
v0.0.42 - https://github.com/SolaceLabs/solace-tryme-cliNOTE: 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.
- 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 |
- 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' successfullyTo 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' successfullyNOTE: 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 |
- Initialize Configuration
stm config init
✔ success success: initialized configuration with default command settings on 'stm-cli-configuration.json' successfully- 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' successfullyTo 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' successfullyNOTE: 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/meOn 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): 100NOTE: 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 [email protected]: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:
- Ask the Solace Community
- The Solace Developer Portal website at: https://solace.dev
Authors
See the list of contributors who participated in this project.
License
See the LICENSE file for details.