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:
rainbow
pulse
strobe
fade
custom (user-defined)
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>
# 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