Joule
  • Welcome to Joule's Docs
  • Why Joule?
    • Joule capabilities
  • What is Joule?
    • Key features
    • The tech stack
  • Use case enablement
    • Use case building framework
  • Concepts
    • Core concepts
    • Low code development
    • Unified execution engine
    • Batch and stream processing
    • Continuous metrics
    • Key Joule data types
      • StreamEvent object
      • Contextual data
      • GeoNode
  • Tutorials
    • Getting started
    • Build your first use case
    • Stream sliding window quote analytics
    • Advanced tutorials
      • Custom missing value processor
      • Stateless Bollinger band analytics
      • IoT device control
  • FAQ
  • Glossary
  • Components
    • Pipelines
      • Use case anatomy
      • Data priming
        • Types of import
      • Processing unit
      • Group by
      • Emit computed events
      • Telemetry auditing
    • Processors
      • Common attributes
      • Filters
        • By type
        • By expression
        • Send on delta
        • Remove attributes
        • Drop all events
      • Enrichment
        • Key concepts
          • Anatomy of enrichment DSL
          • Banking example
        • Metrics
        • Dynamic contextual data
          • Caching architecture
        • Static contextual data
      • Transformation
        • Field Tokeniser
        • Obfuscation
          • Encryption
          • Masking
          • Bucketing
          • Redaction
      • Triggers
        • Change Data Capture
        • Business rules
      • Stream join
        • Inner stream joins
        • Outer stream joins
        • Join attributes & policy
      • Event tap
        • Anatomy of a Tap
        • SQL Queries
    • Analytics
      • Analytic tools
        • User defined analytics
          • Streaming analytics example
          • User defined analytics
          • User defined scripts
          • User defined functions
            • Average function library
        • Window analytics
          • Tumbling window
          • Sliding window
          • Aggregate functions
        • Analytic functions
          • Stateful
            • Exponential moving average
            • Rolling Sum
          • Stateless
            • Normalisation
              • Absolute max
              • Min max
              • Standardisation
              • Mean
              • Log
              • Z-Score
            • Scaling
              • Unit scale
              • Robust Scale
            • Statistics
              • Statistic summaries
              • Weighted moving average
              • Simple moving average
              • Count
            • General
              • Euclidean
        • Advanced analytics
          • Geospatial
            • Entity geo tracker
            • Geofence occupancy trigger
            • Geo search
            • IP address resolver
            • Reverse geocoding
            • Spatial Index
          • HyperLogLog
          • Distinct counter
      • ML inferencing
        • Feature engineering
          • Scripting
          • Scaling
          • Transform
        • Online predictive analytics
        • Model audit
        • Model management
      • Metrics engine
        • Create metrics
        • Apply metrics
        • Manage metrics
        • Priming metrics
    • Contextual data
      • Architecture
      • Configuration
      • MinIO S3
      • Apache Geode
    • Connectors
      • Sources
        • Kafka
          • Ingestion
        • RabbitMQ
          • Further RabbitMQ configurations
        • MQTT
          • Topic wildcards
          • Session management
          • Last Will and Testament
        • Rest endpoints
        • MinIO S3
        • File watcher
      • Sinks
        • Kafka
        • RabbitMQ
          • Further configurations
        • MQTT
          • Persistent messaging
          • Last Will and Testament
        • SQL databases
        • InfluxDB
        • MongoDB
        • Geode
        • WebSocket endpoint
        • MinIO S3
        • File transport
        • Slack
        • Email
      • Serialisers
        • Serialisation
          • Custom transform example
          • Formatters
        • Deserialisers
          • Custom parsing example
    • Observability
      • Enabling JMX for Joule
      • Meters
      • Metrics API
  • DEVELOPER GUIDES
    • Setting up developer environment
      • Environment setup
      • Build and deploy
      • Install Joule
        • Install Docker demo environment
        • Install with Docker
        • Install from source
        • Install Joule examples
    • Joulectl CLI
    • API Endpoints
      • Mangement API
        • Use case
        • Pipelines
        • Data connectors
        • Contextual data
      • Data access API
        • Query
        • Upload
        • WebSocket
      • SQL support
    • Builder SDK
      • Connector API
        • Sources
          • StreamEventParser API
        • Sinks
          • CustomTransformer API
      • Processor API
      • Analytics API
        • Create custom metrics
        • Define analytics
        • Windows API
        • SQL queries
      • Transformation API
        • Obfuscation API
        • FieldTokenizer API
      • File processing
      • Data types
        • StreamEvent
        • ReferenceDataObject
        • GeoNode
    • System configuration
      • System properties
  • Deployment strategies
    • Deployment Overview
    • Single Node
    • Cluster
    • GuardianDB
    • Packaging
      • Containers
      • Bare metal
  • Product updates
    • Public Roadmap
    • Release Notes
      • v1.2.0 Join Streams with stateful analytics
      • v1.1.0 Streaming analytics enhancements
      • v1.0.4 Predictive stream processing
      • v1.0.3 Contextual SQL based metrics
    • Change history
Powered by GitBook
On this page
  • Installation
  • Joule usecase Lifecycle
  • Available Commands
  • Configure command
  • Deploy command
  • List command
  • Inspect command
  • Process command
  • Undeploy command

Was this helpful?

  1. DEVELOPER GUIDES

Joulectl CLI

Use Joulectl to deploy and manage use cases within the Joule platform

PreviousInstall Joule examplesNextAPI Endpoints

Last updated 10 days ago

Was this helpful?

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 .

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

$ 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:

  1. Source data transport

  2. Stream definition

  3. Sink data transport

  4. Use case definition which binds source, stream and sink together

A set of sub command elements provide these functionalities.

We shall use the IoT valve control use case found under the quick start project

Note the --pod option will be used to deploy artefacts to a specifc cluster of Joule nodes

Command: joulectl deploy <sub-command> <json-filename> --pod <pod-name>

Transports

Register transports in to the system.

Transports are reusable across use cases

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>

Note streams and transports cannot be undeployed if there is a dependency on them.

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

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 section.

deployment
here
config
deploy
list
inspect
process
undeploy