CMD API

CMD API

The CMD API provides a simple HTTP endpoint to send commands to OpenHAB items without authentication. It's designed for local automation systems (e.g., scripts, home automation controllers) that need to control OpenHAB items from trusted networks.

Configuration

Add the cmdapi section to your config.local.js under server:

cmdapi: {
    enabled: true,
    allowedSubnets: ['192.168.1.0/24'],
    allowedItems: ['*'],  // Or specific items: ['Light_Kitchen', 'Dimmer_Living']
},

Options

Option	Type	Default	Description
enabled	boolean	false	Enable/disable the CMD API endpoint
allowedSubnets	string[]	[]	CIDR subnets allowed to use this endpoint
allowedItems	string[]	[]	Item names allowed (use '*' for all items)

Usage

Send a GET request to /CMD with the item name as the query parameter key and the state as the value:

GET /CMD?ItemName=State

Examples

# Turn on a light
curl "http://localhost:9080/CMD?Light_Kitchen=ON"

# Set dimmer to 50%
curl "http://localhost:9080/CMD?Dimmer_Living=50"

# Send a string command
curl "http://localhost:9080/CMD?Scene_Selector=MOVIE"

Response Format

All responses are JSON with a result field:

Success

{"result":"success"}

Failure

{"result":"failed","error":"Error description"}

Error Codes

HTTP Status	Error	Description
200	OpenHAB returned XXX	Request reached OpenHAB but item doesn't exist or command failed
400	Invalid query format - expected ?Item=state	Missing or multiple query parameters
400	Invalid item name	Item name contains invalid characters or exceeds length limit
400	Invalid state value	State is empty, too long, or contains control characters
400	Invalid characters in state	State contains control characters
403	IP not allowed	Request IP not in allowedSubnets
403	Item not allowed	Item not in allowedItems list
404	CMD API not enabled	enabled is set to false

Security Considerations

The CMD API is designed for trusted local networks only:

1. No Authentication: Requests bypass the normal authentication system
2. IP Restriction: Only IPs in allowedSubnets can access the endpoint
3. Item Allowlist: Only items in allowedItems can be controlled

Recommendations

• Use specific CIDR ranges (e.g., 192.168.1.0/24) rather than 0.0.0.0/0
• List specific items in allowedItems instead of using '*' when possible
• Never expose this endpoint to the internet
• Use HTTPS if the network is not fully trusted

Validation Rules

Item Names

• Allowed characters: a-z, A-Z, 0-9, _, -
• Maximum length: 100 characters

State Values

• Must not be empty
• Maximum length: 500 characters
• Control characters (except newline/tab) are rejected

Hot Reload

Configuration changes are hot-reloaded without restart. Modifying config.local.js will apply the new cmdapi settings immediately.