Joulectl CLI
Use Joulectl to deploy and manage use cases within the Joule platform
Joulectl helps you deploy and manage use cases within the Joule platform. It uses a context configuration which connects to the desired Joule platform.
Installation
To install joulectl visit here.
pip install joulectl
Joule usecase Lifecycle
Joulectl allows you to manage the entire usecase lifecycle which includes these phases:
Deployment
Getting status
Runtime management
Undeployment
The follwing sections cover each of these areas.
Available Commands
Joulectl has a set of commands to support the deployment and management of use cases for both single node and cluster deployment:
Execute joulectl <command> --help
will show further details on how to use a command.
$ joulectl --help
Usage: joulectl [OPTIONS] COMMAND [ARGS]...
Joule deployment and management tool
joulctl version 0.1.0
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
config Configure tool setting.
deploy Deploy command for transports, streams and use cases.
inspect Get deployed specifications for transports, streams and use...
ls List deployed transports, streams and use cases.
undeploy Undeploy command for transports, streams and use cases.
usecase Management command for use cases
Configure command
Joulectl can be configured to execute commands against a cluster or single node.
Command: joulectl config <sub-command> <arguments>
$ joulectl config --help
Usage: joulectl config [OPTIONS] COMMAND [ARGS]...
Configure joulectl setting.
Options:
--help Show this message and exit.
Commands:
create Create a new configuration file.
show Show configuration setting
update Update configuration setting
create
On first usage of the tool a configuration file must be created. A config.json
file will created using default setting under the ~/.config/joule
directory.
The default setting will be applied for single Joule node operation on 127.0.0.1:9080
$ joulectl config create
Configuration created.
update
To change the host address and port using the update command. The example below configures connects to the Joule Guardian process which manages a cluster of Joule processes, to learn more about Joule's capabilities running in cluster mode under the deployment section.
$ joulectl config update 192.168.1.10:60110
Joule host set to 192.168.1.10:60110
show
Display the current configuration setting.
$ joulectl config show
Key Configuration
---------- ---------------------------
joule_dir /Users/joule/.config/joule
joule_host localhost:60110
Deploy command
Deploying a use requires at minimum four components to be deploy:
Source data transport
Stream definition
Sink data transport
Use case definition which binds source, stream and sink together
A set of sub command elements provide these functionalities.
Command: joulectl deploy <sub-command> <json-filename> --pod <pod-name>
Transports
Register transports in to the system.
Sources
Connect to the MQTT sensor data event source
$ joulectl deploy transport sensor_consumer.json --pod sensor_pod
Host Command Response Message
------------------- ------------------ ---------- ---------------------------------
192.168.86.40:50220 REGISTER_TRANSPORT SUCCESS Transport registered successfully
Sinks
Deploy a MQTT event publisher and a file sink.
$ joulectl deploy transport activation_mqtt_publisher.json --pod sensor_pod
Host Command Response Message
------------------- ------------------ ---------- ---------------------------------
192.168.86.40:50220 REGISTER_TRANSPORT SUCCESS Transport registered successfully
$ joulectl deploy transport activation_file.json --pod sensor_pod
Host Command Response Message
------------------- ------------------ ---------- ---------------------------------
192.168.86.40:50220 REGISTER_TRANSPORT SUCCESS Transport registered successfully
Now list out the deployed transports
$ joulectl list transports
Pod Name Transport Type Created At
---------- ----------------------- ------------- ------ --------------------------
sensor_pod arduino_sensor_consumer mqttConsumer SOURCE 2025-05-03 12:09:04.65979
sensor_pod test_mqtt_publisher mqttPublisher SINK 2025-05-03 12:11:27.069958
sensor_pod activation_file file SINK 2025-05-03 12:12:09.593675
Stream
$ joulectl deploy stream valve_control_stream.json --pod sensor_pod
Host Command Response Message
------------------- --------------- ---------- ------------------------------
192.168.86.40:50220 REGISTER_STREAM SUCCESS Stream registered successfully
Use case
By deploying a use case the Joule platform creates a runtime context which binds all defined dependencies together to act as a single use case unit
$ joulectl deploy usecase valve_control_uc.json --pod sensor_pod
Host Command Response Message
------------------- -------------- ---------- ------------------------------
192.168.86.40:50220 DEPLOY_USECASE SUCCESS Use case deployed successfully
At this point you will have a running use case processing sensor event data and publishing alerts both to MQTT and to file.
List command
List deployed clusters, artefacts and running processes:
Pods
Members
Transports
Streams
Use cases
Command: joulectl ls <type>
Pods
List the deployed clusters joule nodes.
$ joulectl ls pods
Pod Members
---------- ---------
sensor_pod 1
Members
List the cluster connected Joule nodes.
$ joulectl ls members sensor_pod
Host Process Status Created At Updated At
------------- ------------------- -------- ------------------- -------------------
192.168.86.40 192.168.86.40:50220 ONLINE 2025-05-03 12:06:00 2025-05-03 14:31:24
Transports
List deployed transports.
$ joulectl ls transports
Pod Name Transport Type Created At
---------- ----------------------- ------------- ------ --------------------------
sensor_pod sensor_consumer mqttConsumer SOURCE 2025-05-03 12:09:04.65979
sensor_pod mqtt_publisher mqttPublisher SINK 2025-05-03 12:11:27.069958
sensor_pod activation_file file SINK 2025-05-03 12:12:09.593675
Streams
List the deployed stream processing definitions.
$ joulectl ls streams
Pod Name Metrics Enabled Telemetry Enabled Valid From Valid To Created At
---------- -------------------------------- ----------------- ------------------- -------------------------- --------------------- --------------------------
sensor_pod sensor_analytics_processing false false 2025-05-03 12:15:55.335223 2099-12-31 23:59:59.0 2025-05-03 12:15:55.352551
Use cases
List the deployed use cases.
$ joulectl ls usecases
Pod Name Stream Sources Sinks Reference Data Valid From Valid To Created At
---------- ------------------------ -------------------------------- ----------------------- ----------------------------------- ---------------- -------------------------- --------------------- --------------------------
sensor_pod sensor_analytics_uc sensor_analytics_processing sensor_consumer activation_file,mqtt_publisher 2025-05-03 12:17:07.734485 2099-12-31 23:59:59.0 2025-05-03 12:17:07.738864
Inspect command
This command queries the Joule registry for a given data-type and returns the deployed artefact as a file.
Supported sub commands:
usecase
stream
transport
Command: joulectl inspect <sub-command> --help
for required arguments.
$ joulectl inspect usecase sensor_analytics_uc --pod sensor_pod
This will return a sensor_analytics_uc.json
file in to the local directory.
Process command
Control a deployed use case by either pausing processing or resuming the stream processing. This may be useful in the event of debugging.
Command: joulectl process <sub-command> <usecase-name> --pod <pod-name>
Pause
Pause a use case processing
$ joulectl process pause sensor_analytics_uc --pod sensor_pod
Name Command Response
------------------------ ------------- ----------
test_sensor_analytics_uc PAUSE_USECASE SUCCESS
Resume
Resume a use case processing
$ joulectl process resume sensor_analytics_uc --pod sensor_pod
Name Command Response
------------------------ -------------- ----------
test_sensor_analytics_uc RESUME_USECASE SUCCESS
Undeploy command
To undeploy use cases, stream and transport from the Joule platform.
Command: joulectl undeploy <type> <deployment-name> --pod <pod-name>
Usecase
$ joulectl undeploy usecase sensor_analytics_uc --pod sensor_pod
Host Command Response Message
------------------- ---------------- ---------- ----------------------------------
192.168.86.40:50220 UNDEPLOY_USECASE SUCCESS Use case unregistered successfully
Stream
$ joulectl undeploy stream sensor_analytics_processing --pod sensor_pod
Host Command Response Message
------------------- ----------------- ---------- --------------------------------
192.168.86.40:50220 UNREGISTER_STREAM SUCCESS Stream unregistered successfully
Transport
$ joulectl undeploy transport activation_file SINK --pod sensor_pod
Host Command Response Message
------------------- -------------------- ---------- -----------------------------------
192.168.86.40:50220 UNREGISTER_TRANSPORT SUCCESS Transport unregistered successfully
Last updated
Was this helpful?