Adding Your First Device

This guide provides detailed instructions for adding your first Shelly device to the CLI.

Prerequisites#

Before you begin, ensure you have:

• Shelly CLI installed (Installation Guide)
• A Shelly device powered on and connected to your WiFi
• The device IP address or mDNS hostname
• Device authentication credentials (if password-protected)

Finding Your Device#

Option 1: Use Discovery#

The easiest way to find your device:

1

shelly discover

This scans your local network using mDNS and returns all discovered Shelly devices.

Option 2: Check Your Router#

Look in your router’s DHCP client list for devices starting with “shelly”.

Option 3: Use the Shelly App#

If you’ve already configured the device with the Shelly app:

1. Open the Shelly app
2. Tap on your device
3. Go to Settings → Device Information
4. Note the IP address

Option 4: Device Access Point#

New, unconfigured devices broadcast their own WiFi:

1. Connect to the device’s AP (e.g., shelly-plus-1-XXXXXX)
2. The device is at 192.168.33.1
3. Configure WiFi through the web UI first

Registering the Device#

Basic Registration#

1

shelly device add <name> <address>

Example:

1

shelly device add kitchen 192.168.1.100

Rules for device names:

• Use lowercase letters, numbers, and hyphens
• No spaces (use hyphens instead)
• Keep it short and descriptive
• Examples: living-room, kitchen-light, garage-door

Registration with Authentication#

If your device has a password set:

1

shelly device add kitchen 192.168.1.100 --user admin --password yourpassword

Security tip: Avoid passwords in shell history by using a prompt:

1

shelly device add kitchen 192.168.1.100 --user admin --password-stdin <<< "yourpassword"

Registration with Generation Hint#

If auto-detection fails, specify the generation:

1

shelly device add kitchen 192.168.1.100 --generation 2

Updating an Existing Device#

To update credentials or address:

1

shelly device add kitchen 192.168.1.100 --force --user admin --password newpassword

The --force flag overwrites existing device configuration.

Verifying Connection#

After registration, verify the device responds:

1
2

# Get device info
shelly device info kitchen

Expected output:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

Device: kitchen
Address: 192.168.1.100
Model: SNSW-001X16EU (Shelly Plus 1)
Generation: 2
Firmware: 1.0.0 (stable)
MAC: AABBCCDDEEFF
Uptime: 2d 5h 30m
WiFi: Connected (-45 dBm)
Cloud: Disabled
Auth: Enabled

1
2

# Check status
shelly status kitchen

1
2

# Test control
shelly toggle kitchen

Configuration File#

Your device is stored in ~/.config/shelly/config.yaml:

1
2
3
4
5
6
7
8

devices:
  kitchen:
    address: 192.168.1.100
    generation: 2
    model: SNSW-001X16EU
    auth:
      user: admin
      password: yourpassword

Important: Passwords are stored in plain text. Ensure the config file has restricted permissions:

1

chmod 600 ~/.config/shelly/config.yaml

Troubleshooting#

“Device not found” or Connection Timeout#

1
2
3
4
5
6
7
8

# Ping the device
ping 192.168.1.100

# Check if device responds to HTTP
curl http://192.168.1.100/shelly

# For Gen2+, try RPC endpoint
curl http://192.168.1.100/rpc/Shelly.GetDeviceInfo

Possible causes:

• Device on different subnet
• Firewall blocking connections
• Device in AP mode (not connected to your WiFi)

Authentication Failed#

1
2

# Verify credentials via curl
curl -u admin:yourpassword http://192.168.1.100/rpc/Shelly.GetDeviceInfo

Possible causes:

• Incorrect username (try admin)
• Incorrect password
• Auth not enabled on device (try without credentials)

Generation Detection Failed#

Explicitly specify the generation:

1

shelly device add kitchen 192.168.1.100 --generation 2

To determine generation:

• Check model number on the device
• Gen1: Model starts with SH (e.g., SHSW-1)
• Gen2+: Model starts with SN (e.g., SNSW-001X16EU)

Device Shows Offline#

1
2
3
4
5

# Check device status
shelly device info kitchen

# Try direct status
shelly status 192.168.1.100

Possible causes:

• IP address changed (use discovery to find new IP)
• Device rebooting
• Network issues

Next Steps#

Now that you’ve added your first device:

• Create Device Groups - Group multiple devices
• Set Up Scenes - Create multi-device scenes
• Configure Aliases - Create command shortcuts
• Explore the TUI - Visual device control