Somfy CLI

Control your Somfy smart home devices from any device - desktop, server, or automation scripts. Works entirely through your local gateway with no cloud dependencies required.

Why Somfy CLI?

✅ Universal Device Control - Control from any device, not just your mobile app
✅ 100% Local & Private - Communicates directly with your local TaHoma gateway - no cloud required
✅ Automation Ready - Perfect for scripts, cron jobs, and home automation systems

Overview

The Somfy CLI provides comprehensive control over Somfy smart home devices through the TaHoma Local API, allowing you to discover devices, control device states, manage aliases, and monitor device events directly from the command line.

Built on the Somfy SDK for reliable and efficient communication with your TaHoma gateway.

Installation

Homebrew (Recommended)

# Add the tap (one-time setup)
brew tap markusz/somfy-cli

# Install somfy-cli
brew install somfy-cli

# Update to latest version
brew upgrade somfy-cli

Pre-built Binaries

Download the latest release from GitHub Releases:

• macOS: somfy-cli-macos-x86_64 (Intel) or somfy-cli-macos-aarch64 (Apple Silicon)
• Linux: somfy-cli-linux-x86_64
• Windows: somfy-cli-windows-x86_64.exe

# Example for macOS (Intel)
curl -L https://github.com/markusz/somfy-cli/releases/latest/download/somfy-cli-macos-x86_64 -o somfy
chmod +x somfy
sudo mv somfy /usr/local/bin/

From Source

git clone https://github.com/markusz/somfy-cli.git
cd somfy-cli
cargo build --release

The compiled binary will be available at target/release/somfy.

Using Cargo

cargo install --path .

Authentication

The CLI supports multiple authentication methods, with the following order of precedence:

1. Command Line Parameters (Highest Priority)

somfy --api-key YOUR_API_KEY --gateway-url gateway.local.ip --gateway-port 8443 ls

2. Environment Variables

export SOMFY_API_KEY=your_api_key_here
export SOMFY_GATEWAY_HOSTNAME=192.168.1.100
export SOMFY_GATEWAY_PORT=8443
somfy ls

3. Configuration File (env.json)

Create a configuration file at ~/.config/somfy-cli/env.json (or %APPDATA%\somfy-cli\env.json on Windows):

{
  "protocol": "Https",
  "hostname": "192.168.1.100",
  "port": 8443,
  "api_key": "your_api_key_here"
}

Prerequisites

Before using the Somfy CLI, you need:

1. Developer Mode Enabled - Your TaHoma gateway must have developer mode enabled
2. API Key - A valid API key for local access

⚠️ Setup Required: Follow the detailed setup instructions at Somfy TaHoma Developer Mode to enable developer mode and obtain your API key.

Getting Help

The CLI provides comprehensive help documentation for all commands using the --help flag:

# General help
somfy --help

# Help for specific commands
somfy open --help
somfy alias --help
somfy position --help

Commands

Device Control

Open Device

Completely opens a device (blinds, shutters, etc.):

somfy open <device_url_or_alias>

Close Device

Completely closes a device:

somfy close <device_url_or_alias>

Set Position

Moves a device to a specific position (0-100%):

somfy position <device_url_or_alias> <percentage>

Device Information

List Devices

Lists all available devices:

somfy ls

Current Executions

Shows all currently running device executions:

somfy current-execs

Listen for Events

Listens for real-time device events:

somfy listen

Alias Management

Create and manage aliases for device URLs to simplify commands:

Add Alias

somfy alias add <alias_name> <device_url>
somfy alias add <alias_name> <device_url> --overwrite  # Overwrite existing alias

Remove Alias

somfy alias rm <alias_name>

List Aliases

somfy alias ls

Using Aliases

Once created, aliases can be used in place of device URLs:

somfy alias add living-room io://1234-5678-9012/device1
somfy open living-room  # Instead of: somfy open io://1234-5678-9012/device1

Configurable Output Formats

The CLI supports two output formats that can be configured per-command:

JSON Format (Default)

somfy ls --output-style json
# or
somfy -S json ls
somfy ls # Omitting the params defaults to JSON

Example JSON output:

[
  {
    "label": "Living Room Blinds",
    "device_url": "io://1234-5678-9012/device1",
    "controllable_name": "io:StackComponent",
    "states": [
      {
        "name": "core:StatusState",
        "value": "available"
      },
      {
        "name": "core:ClosureState", 
        "value": 75
      }
    ]
  }
]

Output can be piped, e.g.

somfy ls | jq '.[].label'

Table Format

somfy ls --output-style table
# or  
somfy ls -S table

Example table output:

┌────────────────────┬─────────────────────────────┬─────────────────────┬─────────────┬──────────────┬─────────────┬───────────┬───────────────────┬────────────────┬────────────┐
│ Label              │ Device URL                  │ Device Type         │ Open/Close  │ Status       │ Closure (%) │ Tilt (%)  │ 'My' position (%) │ 'My' tilt (%)  │ Is Moving? │
├────────────────────┼─────────────────────────────┼─────────────────────┼─────────────┼──────────────┼─────────────┼───────────┼───────────────────┼────────────────┼────────────┤
│ Living Room Blinds │ io://1234-5678-9012/device1 │ io:StackComponent   │     closed  │    available │          75 │         0 │                50 │              0 │      false │
│ Bedroom Shutters   │ io://1234-5678-9012/device2 │ io:StackComponent   │     closed  │    available │         100 │         0 │                25 │              0 │      false │
└────────────────────┴─────────────────────────────┴─────────────────────┴─────────────┴──────────────┴─────────────┴───────────┴───────────────────┴────────────────┴────────────┘

Configuration

Config parameters

• API Key: Your Somfy API authentication key, obtain from your local gateway (required)
• Gateway URL: Your TaHoma gateway IP address or hostname (required)
• Gateway Port: Port number (optional, defaults to 8443)

Connection Settings

The CLI automatically configures:

• Protocol: HTTPS for secure connections
• Certificate Handling: Automatic handling of self-signed certificates
• Timeouts: Reasonable timeouts for API calls

Examples

Basic Usage

# List all devices
somfy ls

# Open living room blinds using device URL
somfy open io://1234-5678-9012/device1

# Create an alias and use it
somfy alias add living-room io://1234-5678-9012/device1
somfy close living-room

# Set blinds to 50% closed
somfy position living-room 50

# Monitor device events
somfy listen

Authentication Examples

# Using environment variables
export SOMFY_API_KEY=abc123
export SOMFY_GATEWAY_HOSTNAME=192.168.1.100
somfy ls

# Using command line parameters
somfy --api-key abc123 --gateway-url 192.168.1.100 ls

# Using different output formats
somfy ls --output-style table
somfy current-execs -S json

Development

Building

cargo build --release

Running Tests

cargo test

Running in Development Mode

cargo run -- ls
cargo run -- --api-key YOUR_KEY --gateway-url YOUR_GATEWAY ls

Troubleshooting

Common Issues

1. Authentication errors: Verify your API key and gateway URL are correct
2. Network timeouts: Check gateway connectivity and network settings
3. Permission errors: Ensure your API key has necessary permissions
4. Certificate errors: The CLI handles self-signed certificates automatically

Debug Mode

Run with detailed logging:

RUST_LOG=debug cargo run -- ls

License

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