CLI Usage¶

Complete guide to the lifx-emulator command-line interface.

Basic Usage¶

lifx-emulator [OPTIONS] [COMMAND]

Commands¶

lifx-emulator (default)¶

Start the emulator server with configurable devices.

Example:

lifx-emulator --color 2 --multizone 1 --verbose

lifx-emulator list-products¶

List all available LIFX products from the registry.

Example:

lifx-emulator list-products

With filter:

# List only multizone products
lifx-emulator list-products --filter-type multizone

# List only matrix products (tiles)
lifx-emulator list-products --filter-type matrix

lifx-emulator export-config¶

Export persistent storage (device state and scenarios) to a YAML config file. Use this to migrate from the deprecated --persistent workflow to a config file.

Options:

Examples:

# Print exported config to stdout
lifx-emulator export-config

# Export to a file
lifx-emulator export-config --output my-config.yaml

# Export without scenarios
lifx-emulator export-config --no-scenarios --output devices-only.yaml

# Export from custom storage directory
lifx-emulator export-config --storage-dir /path/to/storage

lifx-emulator clear-storage¶

Delete all persistent storage files (device state and scenarios).

Options:

Examples:

# Clear with confirmation prompt
lifx-emulator clear-storage

# Clear without confirmation
lifx-emulator clear-storage --yes

# Clear custom storage directory
lifx-emulator clear-storage --storage-dir /path/to/storage

Configuration Options¶

--config <PATH>¶

Path to a YAML configuration file.

• Default: Auto-detects lifx-emulator.yaml or lifx-emulator.yml in the current directory
• Environment Variable: LIFX_EMULATOR_CONFIG
• Example: --config /path/to/my-config.yaml

Config file resolution order (first match wins):

1. --config flag (explicit path)
2. LIFX_EMULATOR_CONFIG environment variable
3. lifx-emulator.yaml or lifx-emulator.yml in current directory

CLI parameters override config file values. See Configuration File Guide for full details.

Server Options¶

--bind <IP>¶

IPv4 address to bind to.

• Default: 127.0.0.1 (localhost only)
• Example: --bind 0.0.0.0 (all IP addresses)
• Example: --bind 192.168.1.50 (one LAN interface)

Loopback and 0.0.0.0 bind directly. Any other address selects the interface that owns it: the emulator binds 0.0.0.0 on the configured port so that LIFX discovery broadcasts to 255.255.255.255 are received, and only accepts datagrams from peers on that interface's subnets. Replies leave by ordinary routing, so clients on the same LAN see them from the selected address. Datagrams from other interfaces are ignored and counted as packets_filtered in the statistics.

Start-up fails with a clear error when the address is not assigned to any local interface.

--port <PORT>¶

UDP port to listen on.

• Default: 56700 (standard LIFX port)
• Example: --port 56701

--verbose¶

Enable verbose logging showing all packet traffic.

• Default: False
• Example: --verbose

--persistent¶

Enable persistent storage of device state across sessions. Device state (label, power, color, location, group, etc.) is saved to ~/.lifx-emulator/ and automatically restored on restart.

• Default: False
• Example: --persistent

--persistent-scenarios¶

Enable persistent storage of scenario configurations across sessions. Scenarios are saved to ~/.lifx-emulator/scenarios.json. Requires --persistent to be enabled.

• Default: False
• Example: --persistent --persistent-scenarios

API Server Options¶

--api¶

Enable HTTP API server for monitoring and device management. Provides a web dashboard and REST API for runtime control.

• Default: False
• Example: --api

--api-host <IP>¶

IP address for the API server to bind to.

• Default: 127.0.0.1 (localhost only)
• Example: --api-host 0.0.0.0

--api-port <PORT>¶

Port for the API server.

• Default: 8080
• Example: --api-port 9090

--api-activity <BOOL>¶

Enable activity logging in the API (last 100 packets). Disable to reduce traffic and save UI space.

• Default: True
• Example: --api-activity=false

Product Selection¶

--product <product ID>¶

Create devices by product ID from the registry. Can be specified multiple times.

Example:

# Create LIFX A19 (27) and LIFX Z (32)
lifx-emulator --product 27 --product 32

# Create multiple of same product
lifx-emulator --product 55 --product 55 --product 55

No devices are created by default. Use --product, --color, or other device flags to specify devices.

Device Type Options¶

--color <COUNT>¶

Number of color lights to emulate (LIFX A19).

• Default: 0
• Product: 27 (LIFX A19)
• Example: --color 3

--color-temperature <COUNT>¶

Number of color temperature lights to emulate (LIFX Mini White to Warm).

• Default: 0
• Product: 50 (LIFX Mini White to Warm)
• Example: --color-temperature 2

--infrared <COUNT>¶

Number of infrared lights to emulate (LIFX A19 Night Vision).

• Default: 0
• Product: 29 (LIFX A19 Night Vision)
• Example: --infrared 1

--HEV <COUNT>¶

Number of HEV/Clean lights to emulate (LIFX Clean).

• Default: 0
• Product: 90 (LIFX Clean)
• Example: --HEV 2

--multizone <COUNT>¶

Number of multizone devices to emulate (strips/beams).

• Default: 0
• Product: 32 (LIFX Z) or 38 (LIFX Beam with extended)
• Example: --multizone 2

--multizone-zones <COUNT>¶

Number of zones per multizone device. If not specified, uses product defaults:

• LIFX Z: 16 zones

• LIFX Beam: 80 zones

• Default: None (uses product defaults)

• Example: --multizone-zones 24

--multizone-extended / --no-multizone-extended¶

Enable or disable extended multizone support for multizone devices.

• Default: True (creates LIFX Beam with firmware 3.70)
• Enabled: --multizone-extended (default, firmware 3.70)
• Disabled: --no-multizone-extended (creates LIFX Z, firmware 2.60)
• Example: --no-multizone-extended --multizone-zones 16

--tile <COUNT>¶

Number of tile devices to emulate (LIFX Tile).

• Default: 0
• Product: 55 (LIFX Tile)
• Example: --tile 1

--tile-count <COUNT>¶

Number of tiles on each LIFX Tile chain, from 1 to 5. If not specified, uses the product default (5 for LIFX Tile).

• Default: None (uses product defaults)
• Example: --tile-count 3

--tile-width <zones> / --tile-height <zones>¶

--switch <COUNT>¶

Number of LIFX Switch devices to emulate (relay-based switches with no lighting).

• Default: 0
• Product: 70 (LIFX Switch)
• Example: --switch 2

Switch devices have has_relays=True and has_buttons=True capabilities but do not support Light, MultiZone, or Tile protocol packets. They respond with StateUnhandled (packet 223) to unsupported requests.

serial Options¶

--serial-prefix <PREFIX>¶

serial prefix (6 hex characters).

• Default: d073d5
• Example: --serial-prefix cafe00

serials are formatted as <prefix><suffix> where suffix is auto-incremented starting from serial-start.

--serial-start <NUMBER>¶

Starting serial suffix.

• Default: 1
• Example: --serial-start 100

Complete Examples¶

Using a Config File¶

# Auto-detect lifx-emulator.yaml in current directory
lifx-emulator

# Explicit config file
lifx-emulator --config my-setup.yaml

Single Color Light¶

# Create one color light
lifx-emulator --color 1

Verbose Mode¶

# Show all packet traffic
lifx-emulator --color 1 --verbose

Custom Port¶

# Use port 56701
lifx-emulator --color 1 --port 56701

Multiple Device Types¶

# 2 color lights, 1 multizone, 1 tile
lifx-emulator --color 2 --multizone 1 --tile 1

Extended Multizone¶

# LIFX Beam with 60 zones
lifx-emulator --multizone 1 --multizone-extended --multizone-zones 60

Specific Products¶

# LIFX A19, LIFX Z, and LIFX Tile
lifx-emulator --product 27 --product 32 --product 55

Mix Products and Types¶

# Specific product + additional generic devices
lifx-emulator --product 27 --color 2 --multizone 1

Custom serials¶

# Custom prefix and starting number
lifx-emulator --serial-prefix cafe00 --serial-start 100 --color 3
# Creates: cafe00000064, cafe00000065, cafe00000066

Only Specific Types¶

# Only infrared, HEV, and switches
lifx-emulator --infrared 3 --HEV 2 --switch 2

Discovery Testing¶

# Create many devices for load testing
lifx-emulator --color 10 --multizone 5 --tile 3

Localhost Only¶

# Bind to localhost for security
lifx-emulator --color 1 --bind 127.0.0.1 --verbose

With HTTP API¶

# Enable web dashboard and REST API
lifx-emulator --api --color 2 --multizone 1

# Custom API port
lifx-emulator --color 1 --api --api-port 9090

# API without activity logging (reduces traffic)
lifx-emulator --color 1 --api --api-activity=false

Non-Extended Multizone¶

# Create LIFX Z (non-extended, 16 zones max)
lifx-emulator --multizone 2 --no-multizone-extended --multizone-zones 16

List Products Command¶

Basic List¶

lifx-emulator list-products

Output:

LIFX Product Registry (137 products)

 product ID │ Product Name                              │ Capabilities
─────┼───────────────────────────────────────────┼─────────────────────
  27 │ LIFX A19                                  │ full color
  29 │ LIFX A19 Night Vision                     │ full color, infrared
  32 │ LIFX Z                                    │ full color, multizone
  38 │ LIFX Beam                                 │ full color, extended-multizone
  55 │ LIFX Tile                                 │ full color, matrix
  90 │ LIFX Clean                                │ full color, HEV
 ...

Filter by Type¶

# Only multizone products
lifx-emulator list-products --filter-type multizone

# Only matrix products
lifx-emulator list-products --filter-type matrix

# Only HEV products
lifx-emulator list-products --filter-type HEV

# Only infrared products
lifx-emulator list-products --filter-type infrared

# Only full color products
lifx-emulator list-products --filter-type color

Tips¶

Quick Testing¶

For quick testing, use verbose mode to see all traffic:

lifx-emulator --color 1 --verbose

Visual Monitoring¶

Use the HTTP API for visual monitoring during development:

lifx-emulator --color 1 --api --verbose
# Open http://localhost:8080 in your browser

The web dashboard shows: - Real-time server statistics - List of all devices - Recent packet activity (last 100 packets) - REST API for runtime device management

CI/CD Integration¶

Use specific ports and localhost binding in CI:

lifx-emulator --color 1 --bind 127.0.0.1 --port 56701 &
EMULATOR_PID=$!
# Run your tests
kill $EMULATOR_PID

Product Discovery¶

List products to find the right product ID for your tests:

lifx-emulator list-products --filter-type multizone

State Preservation¶

Use a config file to define device state for reproducible test runs:

# Define devices in a config file
lifx-emulator --config my-devices.yaml

See the Configuration File Guide for details on defining device state.

Realistic Configurations¶

Use product defaults for realistic device configurations:

# LIFX Beam with default 80 zones (extended by default)
lifx-emulator --multizone 1

# LIFX Tile with default 5 tiles
lifx-emulator --tile 1

Development Mode¶

For development with full observability:

# Verbose logging, API dashboard
lifx-emulator --verbose --api --color 2 --multizone 1

Testing Mode¶

For testing network issues and edge cases:

# API enabled for runtime scenario configuration
lifx-emulator --api --color 3
# Then use the REST API to configure packet loss, delays, etc.

Next Steps¶

• Device Types Guide - Learn about each device type
• Testing Scenarios - Configure error scenarios
• API Reference - Python API documentation
• Tutorials - More usage examples