node-red-contrib-balena-cli 1.0.0

A comprehensive Node-RED wrapper for Balena CLI providing device management, fleet operations, SSH access, and variable management for IoT deployments

npm install node-red-contrib-balena-cli

node-red-contrib-balena-cli

A comprehensive Node-RED wrapper for the Balena CLI, providing powerful IoT device and fleet management capabilities directly within Node-RED flows.

Overview

This Node-RED contribution package provides five specialized nodes that wrap the Balena CLI, enabling seamless integration of Balena IoT operations into Node-RED automation workflows:

• balena-device - Device management and control
• balena-fleet - Fleet lifecycle and configuration management
• balena-ssh - SSH access and command execution on devices
• balena-variables - Environment variable management for fleets and devices
• balena-deploy - Code deployment and release management

Features

🚀 Device Management

• List and filter devices by fleet
• Get detailed device information
• Enable/disable local development mode
• Restart, shutdown, and control device power states
• Retrieve device logs with filtering options
• Move devices between fleets
• Rename and tag devices

🏗️ Fleet Operations

• Create, delete, and rename fleets
• List fleets with organization filtering
• Manage releases and deployment strategies
• Pin specific releases or track latest
• Generate fleet configurations
• Fleet-wide restart and purge operations
• Tag management for fleet organization

🔧 SSH & Remote Access

• Execute commands on devices via SSH
• Access specific containers/services
• Create SSH tunnels for port forwarding
• Host OS command execution
• Interactive session connection info
• File transfer capabilities (placeholder)

⚙️ Variable Management

• Set, get, and remove environment variables
• Support for both fleet-level and device-level variables
• Configuration variable management
• Batch operations for multiple variables
• Variable renaming and bulk operations

📦 Deployment & Build

• Push code to fleets with automatic building
• Local builds without deployment
• Deploy pre-built Docker images
• OS image preloading and configuration
• Release finalization and invalidation
• Device fleet joining/leaving operations

🎯 Advanced Features

• Intelligent Caching - Configurable caching for read operations
• Real-time Status Updates - Visual feedback during long operations
• Flexible Configuration - Override settings via message properties
• Error Handling - Comprehensive error reporting and recovery
• Timeout Management - Configurable timeouts for all operations
• Output Formats - JSON and text output options

Installation

Prerequisites

1. Balena CLI - Install the Balena CLI and ensure it's in your system PATH:

   npm install -g balena-cli
   

2. Authentication - Login to your Balena account:

   balena login
   

3. Node-RED - Ensure Node-RED is installed and running

Install the Package

Via Node-RED Palette Manager

1. Open Node-RED in your browser
2. Go to the hamburger menu → Manage Palette
3. Click the "Install" tab
4. Search for node-red-contrib-balena-cli
5. Click "Install"

Via npm

cd ~/.node-red
npm install node-red-contrib-balena-cli

Manual Installation

git clone https://github.com/MadnessEngineering/node-red-contrib-balena-cli.git
cd node-red-contrib-balena-cli
npm install
npm link
cd ~/.node-red
npm link node-red-contrib-balena-cli

Quick Start

Basic Device Listing

{
  "operation": "list",
  "fleet": "my-iot-fleet"
}

SSH Command Execution

{
  "operation": "command",
  "deviceUuid": "1234567890abcdef",
  "command": "df -h"
}

Environment Variable Management

{
  "operation": "set",
  "scope": "fleet",
  "target": "my-iot-fleet",
  "variableName": "API_URL",
  "variableValue": "https://api.example.com"
}

Code Deployment

{
  "operation": "push",
  "fleetName": "my-iot-fleet",
  "sourceDirectory": "/path/to/code",
  "nocache": true
}

Node Documentation

balena-device

Category: balena
Color: #00AEEF (Balena Blue)
Icon: fa-microchip

Manages Balena devices with operations including listing, information retrieval, power control, log access, and fleet management.

Operations:

• list - List devices (optionally filtered by fleet)
• info - Get device details
• enable_local_mode / disable_local_mode - Development mode control
• restart / shutdown - Power management
• logs - Retrieve device logs
• move - Transfer device between fleets
• rename - Change device name

balena-fleet

Category: balena
Color: #4CAF50 (Green)
Icon: fa-ship

Comprehensive fleet management including creation, configuration, release management, and device operations.

Operations:

• list / info - Fleet discovery and details
• create / delete - Fleet lifecycle
• rename - Fleet naming
• releases - Release listing
• pin_release / track_latest - Release strategy
• config - Configuration generation
• restart / purge - Fleet-wide operations
• devices - Fleet device listing
• tags / set_tag / remove_tag - Tag management

balena-ssh

Category: balena
Color: #FFA500 (Orange)
Icon: fa-terminal

Provides SSH access to Balena devices for command execution, tunneling, and file operations.

Operations:

• command - Execute commands on devices
• interactive - Get connection info for manual SSH
• tunnel - Create SSH port forwarding
• file_transfer - File upload/download (placeholder)
• host_os - Host OS command execution

balena-variables

Category: balena
Color: #9C27B0 (Purple)
Icon: fa-cog

Manages environment and configuration variables at both fleet and device levels.

Operations:

• list / get - Variable retrieval
• set / remove - Variable management
• rename - Variable renaming
• config_vars / set_config_var - Configuration variables
• batch_set / bulk_remove - Bulk operations

balena-deploy

Category: balena
Color: #FF5722 (Deep Orange)
Icon: fa-rocket

Handles code deployment, building, and release management for Balena applications.

Operations:

• push - Build and deploy code
• build - Local build without deployment
• deploy - Deploy pre-built images
• preload - OS image preloading
• release_finalize / release_invalidate - Release management
• join / leave - Device fleet management
• os_configure / local_configure - OS and device configuration

Configuration Options

Common Settings

• Name - Node display name
• Operation - Primary operation to perform
• Timeout - Command execution timeout (milliseconds)
• Output Format - JSON or text output
• Enable Caching - Cache read operations for performance
• Cache Duration - How long to cache results (seconds)

Node-Specific Settings

Each node has specific configuration options relevant to its operations:

• Device nodes require Device UUIDs
• Fleet nodes require Fleet names and optionally Device types
• SSH nodes require connection parameters
• Variable nodes require scope (fleet/device) and target
• Deploy nodes require source directories and build options

Message Properties

All nodes support configuration override via message properties. Common properties include:

msg = {
  operation: "list",           // Override configured operation
  timeout: 60000,             // Override timeout
  cached: false,              // Force fresh execution
  // Node-specific properties...
  deviceUuid: "...",          // For device operations
  fleetName: "...",           // For fleet operations  
  command: "...",             // For SSH operations
  variableName: "...",        // For variable operations
  sourceDirectory: "..."      // For deployment operations
}

Examples

Fleet Device Monitoring

Create a flow that monitors all devices in a fleet and alerts on offline devices:

1. Inject node → triggers every 5 minutes
2. balena-device → list operation with fleet filter
3. Function node → filter offline devices
4. Switch node → route if any offline devices found
5. Notification → send alert

Automated Deployment Pipeline

Create a CI/CD pipeline that deploys code when changes are detected:

1. File Watch → monitors code directory
2. balena-deploy → push operation with nocache option
3. balena-device → restart all devices in fleet
4. Notification → deployment success/failure alert

Environment Configuration Management

Manage environment variables across fleets:

1. HTTP In → receives configuration updates
2. Function node → processes configuration changes
3. balena-variables → batch_set operation
4. balena-fleet → restart to apply changes
5. HTTP Response → confirm completion

Remote Device Diagnostics

SSH into devices to run diagnostic commands:

1. Dashboard Input → select device and command
2. balena-ssh → command operation
3. Function node → format output
4. Dashboard Output → display results

Error Handling

All nodes provide comprehensive error handling:

• CLI Errors - Balena CLI command failures
• Authentication - Invalid or expired credentials
• Network Issues - Connectivity problems
• Timeout Errors - Operation timeouts
• Validation - Invalid parameters or missing requirements

Error information is available in:

• Node status indicators
• msg.error property
• Node-RED debug panel
• Console logs

Performance & Caching

Caching Strategy

• Read operations (list, info, logs) are cached by default
• Write operations always execute fresh
• Cache keys include operation and parameters
• Configurable cache duration per node

Timeout Management

• Default timeouts are optimized per operation type
• Build operations: 30 minutes
• Standard operations: 30 seconds
• SSH operations: 30 seconds
• Configurable per node instance

Resource Usage

• Minimal memory footprint with optional caching
• Efficient CLI command execution
• Concurrent operation support
• Background process management for long operations

Troubleshooting

Common Issues

"balena command not found"

• Ensure Balena CLI is installed and in PATH
• Verify installation: which balena

"Authentication failed"

• Login to Balena: balena login
• Check authentication: balena whoami

"Device not found"

• Verify device UUID is correct
• Ensure device is online and accessible
• Check fleet permissions

"SSH connection failed"

• Verify device is online
• Ensure SSH is enabled on device
• Check network connectivity

Debug Mode

Enable debug logging by setting the environment variable:

DEBUG=node-red-contrib-balena-cli:* node-red

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

1. Clone the repository
2. Install dependencies: npm install
3. Link for development: npm link
4. Run tests: npm test

Reporting Issues

Please report issues on our GitHub Issues page with:

• Node-RED version
• Balena CLI version
• Operating system
• Detailed error messages
• Steps to reproduce

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Documentation: GitHub Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Acknowledgments

• Balena - For the excellent IoT platform and CLI
• Node-RED - For the fantastic flow-based programming environment
• MadnessEngineering - Project maintainers

---

Made with ❤️ by the MadnessEngineering team