BusyTag.CLI/
├── Program.cs # Main application entry point
├── BusyTag.CLI.csproj # Project configuration
└── README.md # This file
🚀 Installation Methods
Method 1: Homebrew (macOS - Recommended)
Install using Homebrew for the easiest setup on macOS:
# Add the BusyTag tap
brew tap busy-tag/busytag
# Install BusyTag CLI
brew install busytag-cli
# Verify installation
busytag-cli --version
# Update to latest version
brew update && brew upgrade busytag-cli
# Uninstall if needed
brew uninstall busytag-cli
✅ Advantages:
No .NET runtime required - Self-contained executable
Automatic updates - Homebrew keeps it current
Native performance - Optimized for your Mac architecture
Easy management - Standard Homebrew commands
Method 2: .NET Global Tool (Cross-Platform)
Install as a global tool using the .NET CLI (requires .NET 8.0+ runtime):
# Install .NET 8.0+ first if not already installed
# Download from: https://dotnet.microsoft.com/download
# Install the latest version
dotnet tool install -g BusyTag.CLI
# Verify installation
busytag-cli --version
# Update to latest version
dotnet tool update -g BusyTag.CLI
# Uninstall if needed
dotnet tool uninstall -g BusyTag.CLI
Method 3: From Source
For development or building from source:
# Clone the repository
git clone https://github.com/busy-tag/busytag-cli.git
cd busytag-cli/BusyTag.CLI
# Build and run
dotnet build -c Release
dotnet run -- --help
# Or build self-contained executable
dotnet publish -c Release --self-contained -r win-x64 # Windows
dotnet publish -c Release --self-contained -r osx-x64 # macOS Intel
dotnet publish -c Release --self-contained -r osx-arm64 # macOS Apple Silicon
dotnet publish -c Release --self-contained -r linux-x64 # Linux
📖 Complete Command Reference
Device Management Commands
Device Discovery
busytag-cli scan # Scan for devices
busytag-cli list # Alias for scan
Connection Management
busytag-cli connect <port> # Connect to specific device
busytag-cli info <port> # Show device information
busytag-cli restart <port> # Restart device remotely
Display Control Commands
Color Control
busytag-cli color <port> <color> [brightness] [led_bits]
Color Formats:
Named colors:red, green, blue, yellow, cyan, magenta, white, off
Hex colors:FF0000, #FF0000
RGB values:255,0,0
Parameters:
brightness: 0-100 (default: 100)
led_bits: 1-127 (default: 127, controls which LEDs to light)
Examples:
busytag-cli color COM3 red # Full red
busytag-cli color COM3 red 75 # Red at 75% brightness
busytag-cli color COM3 FF0000 50 127 # Hex red, 50% brightness, all LEDs
busytag-cli color COM3 255,128,0 # Orange using RGB
busytag-cli color COM3 blue 100 64 # Blue on specific LED pattern
Brightness Control
busytag-cli brightness <port> <level> # Set brightness (0-100)
Pattern Control
busytag-cli pattern <port> <pattern_name> # Apply LED pattern
Available patterns:
Default
Police 1
Police 2
Red flashes
Green flashes
Blue flashes
Yellow flashes
Cyan flashes
Magenta flashes
White flashes
Red running
Green running
Blue running
Yellow running
Cyan running
Magenta running
White running
Red pulses
Green pulses
Blue pulses
Yellow pulses
Cyan pulses
Magenta pulses
White pulses
Image Display
busytag-cli show <port> <filename> # Display image file
busytag-cli display <port> <filename> # Alias for show
File Management Commands
Upload Operations
busytag-cli upload <port> <file_path> # Upload file to device
Only use firmware files specifically designed for your device
Ensure a stable power supply during update
Do not disconnect device during firmware update
Keep backup firmware files for recovery
Information Commands
busytag-cli version # Show CLI version
busytag-cli --version # Alternative version command
busytag-cli -v # Short version command
busytag-cli help # Show help information
busytag-cli --help # Alternative help command
busytag-cli -h # Short help command
🔧 Advanced Usage
Interactive Mode
Launch interactive mode for guided operations:
busytag-cli
Interactive Mode Features:
🔄 Automatic device discovery every 3 seconds
📊 Real-time progress indicators with detailed statistics
🛡️ Safe operation confirmations for destructive actions
📈 Detailed storage analysis and file management
🎛️ Guided workflows for complex operations
📋 Device health monitoring and diagnostics
Environment Configuration
Set environment variables for default behavior:
# Windows
set BUSYTAG_DEFAULT_PORT=COM3
set BUSYTAG_TIMEOUT=5000
set BUSYTAG_SCAN_INTERVAL=3000
set BUSYTAG_DEBUG=1
# macOS/Linux
export BUSYTAG_DEFAULT_PORT="/dev/cu.usbserial-xyz" # macOS
# export BUSYTAG_DEFAULT_PORT="/dev/ttyUSB0" # Linux
export BUSYTAG_TIMEOUT=5000
export BUSYTAG_SCAN_INTERVAL=3000
export BUSYTAG_DEBUG=1
🛠️ Development
Building from Source
Prerequisites
.NET 8.0 SDK or later
Git
Build Commands
# Clone repository
git clone https://github.com/busy-tag/busytag-cli.git
cd busytag-cli/BusyTag.CLI
# Restore dependencies
dotnet restore
# Build in Debug mode
dotnet build
# Build in Release mode
dotnet build -c Release
# Run tests
dotnet test
# Run the application
dotnet run -- <arguments>
This project is licensed under the MIT License. See the main repository LICENSE file for details.
📈 Version History
v0.5.0 (Latest)
Updated library versions
Enhanced device communication stability
Improved error handling
v0.4.1
Project cleanup and code optimization
Minor bug fixes
v0.4.0
Updated library versions
Performance improvements
Better compatibility across platforms
v0.3.6
General version update
Stability improvements
v0.3.5
Fixed Homebrew formula path
Enhanced macOS installation process
v0.3.4 & v0.3.3
Homebrew support and automated releases
Native executables for better performance
Minor updates and code refinements
v0.3.2 & v0.3.1
Project file reorganization
Debug improvements
v0.3.0
Added Homebrew automation
Improved deployment process
v0.2.0
Major command improvements and bug fixes
Enhanced documentation
v0.1.0
Initial public release
Core CLI functionality
Device discovery and basic operations
🎯 Performance Optimization
Best Practices
File Operations
# Check available space before large uploads
busytag-cli storage COM3
# Use appropriate file formats
# PNG: Best for static images, smaller file sizes
# GIF: Required for animations, larger file sizes
# Optimize images before upload
# Use tools like pngquant, imageoptim, or tinypng
Batch Operations
# Group related operations to reduce connection overhead
# Good:
busytag-cli upload COM3 file1.png
busytag-cli upload COM3 file2.png
busytag-cli show COM3 file1.png
# Better: Use scripts that maintain connection state
# (Interactive mode handles this automatically)
Connection Management
# For automation, use environment variables to reduce setup time
export BUSYTAG_DEFAULT_PORT="COM3"
export BUSYTAG_TIMEOUT="10000"
# Then commands don't need port specification
busytag-cli color red 75
busytag-cli upload image.png
Memory and Resource Usage
The CLI application is designed to be lightweight:
Memory footprint: ~10-50MB depending on operation
CPU usage: Minimal during normal operations
Network usage: None (local device communication only)
Storage: Self-contained executable ~20-60MB depending on platform
🔐 Security Considerations
Device Access
CLI requires direct access to serial/USB ports
On Linux, user must be in dialout group
On macOS/Windows, admin privileges may be required for driver installation
File Handling
Always validate file paths and names before upload
Be cautious with firmware files - only use trusted sources
Consider scanning uploaded files for malware in shared environments
Automation Security
# Use absolute paths in automation scripts
busytag-cli upload COM3 "/full/path/to/file.png"
# Validate inputs in scripts
if [[ -f "$UPLOAD_FILE" ]]; then
busytag-cli upload "$PORT" "$UPLOAD_FILE"
else
echo "Error: File not found: $UPLOAD_FILE"
exit 1
fi
# Set appropriate file permissions
chmod 600 /path/to/automation-script.sh
🌐 Internationalization
The CLI currently supports English output. For international users:
# For Homebrew users
brew update && brew upgrade busytag-cli
# For .NET tool users
dotnet tool update -g BusyTag.CLI
Check for breaking changes:
Command syntax remains the same
New features available (check changelog)
Environment variable names unchanged
Update automation scripts:
Test all automation scripts with new version
Update any hardcoded version checks
Take advantage of new features
Backup and Recovery
Before major updates:
# Backup current configuration
cp ~/.busytag/config.json ~/.busytag/config.json.backup
# Backup automation scripts
tar -czf busytag-scripts-backup.tar.gz /path/to/scripts/
# Test new version in isolation
busytag-cli --version
busytag-cli help
📞 Support and Community
Getting Help
Documentation: Check this comprehensive guide first
Discussions: Use GitHub Discussions for questions and community support
Reporting Bugs
When reporting bugs, include:
# System information
busytag-cli --version
uname -a # Linux/macOS
systeminfo # Windows
# Device information
busytag-cli scan
busytag-cli info <port>
# Error logs (if available)
cat /var/log/busytag-cli.log
# Steps to reproduce
# Expected vs actual behavior
# Screenshots or terminal output