node-red-contrib-balena-cli 1.1.0
A comprehensive Node-RED wrapper for Balena CLI providing device management, fleet operations, SSH access, and variable management for IoT deployments
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 six specialized nodes that wrap the Balena CLI, enabling seamless integration of Balena IoT operations into Node-RED automation workflows:
- balena-config: Configuration node for authentication and connection management
- 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
- balena-supervisor: Local supervisor operations for nodes running on balena devices
Authentication
Balena Configuration Node
The balena-config
node provides centralized authentication management for all Balena operations. It supports three login methods:
- Email & Password - Traditional login with Balena account credentials
- API Token - Token-based authentication (recommended for production)
- Browser Login - Interactive browser-based login (development only)
Getting API Tokens
For production deployments, API tokens are recommended:
- Login to the Balena Dashboard
- Go to Preferences → Access Tokens
- Click "Create API Token"
- Give it a name and copy the token
- Use the token in your
balena-config
node
openBalena Support
For openBalena instances, simply change the API URL in the config node to match your deployment (e.g., https://api.openbalena.local
).
Security Features
- Credentials are encrypted and stored securely by Node-RED
- Automatic authentication and session management
- Support for custom Balena API endpoints
- Configurable auto-login behavior
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
Balena CLI - Install the Balena CLI and ensure it's in your system PATH:
npm install -g balena-cli
Balena Account - You'll need either:
- A Balena Cloud account (free at balena.io)
- Access to an openBalena instance
- An API token for authentication
Node-RED - Ensure Node-RED is installed and running
Note: You no longer need to manually login to the Balena CLI as authentication is handled automatically by the balena-config
node.
Install the Package
Via Node-RED Palette Manager
- Open Node-RED in your browser
- Go to the hamburger menu → Manage Palette
- Click the "Install" tab
- Search for
node-red-contrib-balena-cli
- 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
1. Setup Authentication
First, create a balena-config
node:
- Drag a
balena-config
node to your flow - Double-click to configure it
- Choose your login method (Email/Password, API Token, or Browser)
- Enter your credentials
- Test the connection
- Deploy the configuration
2. Basic Device Listing
{
"operation": "list",
"fleet": "my-iot-fleet"
}
3. SSH Command Execution
{
"operation": "command",
"deviceUuid": "1234567890abcdef",
"command": "df -h"
}
4. Environment Variable Management
{
"operation": "set",
"scope": "fleet",
"target": "my-iot-fleet",
"variableName": "API_URL",
"variableValue": "https://api.example.com"
}
Note: balena-variables
and balena-deploy
nodes will be updated with authentication integration in v1.2.0. For now, ensure you're logged in via the CLI manually when using these nodes.
5. Code Deployment
{
"operation": "push",
"fleetName": "my-iot-fleet",
"sourceDirectory": "/path/to/code",
"nocache": true
}
📚 Examples & Templates
The package includes comprehensive example flows to help you get started quickly:
Ready-to-Use Examples
examples/basic-device-monitoring.json
- Device health monitoring and alertingexamples/fleet-management.json
- Fleet operations and release managementexamples/ssh-remote-diagnostics.json
- Remote device diagnostics and troubleshootingexamples/cicd-deployment-pipeline.json
- Complete CI/CD pipeline with rollback
How to Import Examples
- Open Node-RED → Menu → Import
- Select "choose file" and browse to the
examples/
directory - Choose an example JSON file
- Configure with your API tokens and device/fleet details
- Deploy and test!
For detailed setup instructions and customization tips, see examples/README.md
.
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 detailsenable_local_mode
/disable_local_mode
- Development mode controlrestart
/shutdown
- Power managementlogs
- Retrieve device logsmove
- Transfer device between fleetsrename
- Change device nameblink
- Blink device LED for identificationping
- Check device connectivity status
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 detailscreate
/delete
- Fleet lifecyclerename
- Fleet namingreleases
- Release listingpin_release
/track_latest
- Release strategyconfig
- Configuration generationrestart
/purge
- Fleet-wide operationsdevices
- Fleet device listingtags
/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 devicesinteractive
- Get connection info for manual SSHtunnel
- Create SSH port forwardingfile_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 retrievalset
/remove
- Variable managementrename
- Variable renamingconfig_vars
/set_config_var
- Configuration variablesbatch_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 codebuild
- Local build without deploymentdeploy
- Deploy pre-built imagespreload
- OS image preloadingrelease_finalize
/release_invalidate
- Release managementjoin
/leave
- Device fleet managementos_configure
/local_configure
- OS and device configuration
balena-supervisor
Category: balena Color: #8cc8ff (Light Blue) Icon: balena.png
Manages local supervisor operations for nodes running ON balena devices (not remote management).
Operations:
ping
- Check supervisor connectivityblink
- Blink device LED for identificationdevice
- Get device state informationrestart
- Restart a specific service/containerreboot
- Reboot the entire deviceshutdown
- Shutdown the devicepurge
- Purge application dataupdate
- Trigger application updatelock
- Lock updatesunlock
- Unlock updatesapps
- Get application statelogs
- Get supervisor logs
Requirements:
- Must be running on a balena device
- Requires
BALENA_SUPERVISOR_ADDRESS
andBALENA_SUPERVISOR_API_KEY
environment variables
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:
- Inject node → triggers every 5 minutes
- balena-device →
list
operation with fleet filter - Function node → filter offline devices
- Switch node → route if any offline devices found
- Notification → send alert
Automated Deployment Pipeline
Create a CI/CD pipeline that deploys code when changes are detected:
- File Watch → monitors code directory
- balena-deploy →
push
operation with nocache option - balena-device →
restart
all devices in fleet - Notification → deployment success/failure alert
Environment Configuration Management
Manage environment variables across fleets:
- HTTP In → receives configuration updates
- Function node → processes configuration changes
- balena-variables →
batch_set
operation - balena-fleet →
restart
to apply changes - HTTP Response → confirm completion
Remote Device Diagnostics
SSH into devices to run diagnostic commands:
- Dashboard Input → select device and command
- balena-ssh →
command
operation - Function node → format output
- 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
- Clone the repository
- Install dependencies:
npm install
- Link for development:
npm link
- 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