openhab-rest-cli

name	openhab-rest-cli
description	Control and query an openHAB smart home system via the openhab CLI. Manages items (lights, switches, sensors, dimmers) and automation rules through the openHAB REST API. Use when the user asks to control smart home devices, check device states, list home automation items or rules, send commands to openHAB, or interact with their openHAB instance in any way. Triggers on mentions of openHAB, home automation, smart home, IoT devices, items, switches, dimmers, sensors, or automation rules.
license	MIT
compatibility	Requires Node.js >= 18 and network access to an openHAB server.
metadata	{"author":"alackmann","version":"0.1.0"}

openHAB REST CLI

A CLI tool for interacting with an openHAB home automation server. It manages items (devices/sensors) and automation rules via the openHAB REST API.

Setup

The CLI requires an openHAB server URL. Configuration is resolved in priority order:

1. CLI flags: --url <url> and --token <token>
2. Environment variables: OPENHAB_URL and OPENHAB_TOKEN
3. Config file: ~/.openhab-cli.json with "url" and "token" keys (or custom path via --config <path>)

The token is optional for unauthenticated openHAB instances.

If not installed globally, run via npx openhab-rest-cli or build from source:

npm install && npm run build
node dist/index.js --url http://openhab:8080 items list

Quick reference

Always use --json for machine-readable output when processing results programmatically.

Items commands

# List all items (or filter by type/tags)
openhab-rest-cli items list --json
openhab-rest-cli items list --type Switch --json
openhab-rest-cli items list --tags Lighting --json

# Get full details of a single item
openhab-rest-cli items get LivingRoom_Light --json

# Get just the current state value
openhab-rest-cli items state LivingRoom_Light

# Update an item's state
openhab-rest-cli items update LivingRoom_Light ON

# Send a command to an item
openhab-rest-cli items command LivingRoom_Dimmer 50

Rules commands

# List all automation rules
openhab-rest-cli rules list --json

# Get details of a specific rule
openhab-rest-cli rules get my-rule-uid --json

# Execute a rule immediately
openhab-rest-cli rules run my-rule-uid

Common item types and commands

Item type	Typical commands	Example
Switch	ON, OFF	openhab-rest-cli items command MySwitch ON
Dimmer	ON, OFF, 0-100	openhab-rest-cli items command MyDimmer 75
Color	ON, OFF, H,S,B	openhab-rest-cli items command MyColor 120,100,50
Rollershutter	UP, DOWN, STOP, 0-100	openhab-rest-cli items command MyShutter UP
Number	numeric value	openhab-rest-cli items update Temperature 22.5
String	any string	openhab-rest-cli items update MyString "hello"
Contact	OPEN, CLOSED	read-only sensor, use state to check

Workflow: discover then act

1. List items to discover what's available: openhab-rest-cli items list --json
2. Filter by type or tags if needed: openhab-rest-cli items list --type Switch --json
3. Get details of a specific item to see its state, metadata, and available commands: openhab-rest-cli items get <name> --json
4. Send a command or update state as needed

For rules, list first (openhab-rest-cli rules list --json), inspect (openhab-rest-cli rules get <uid> --json), then run (openhab-rest-cli rules run <uid>).

JSON output format

With --json, items return an EnrichedItemDTO object (or array) with fields: name, type, state, label, category, tags, groupNames, stateDescription, commandDescription, editable, and more.

Rules return an EnrichedRuleDTO object (or array) with fields: uid, name, description, status (with status, statusDetail), tags, triggers, conditions, actions, visibility, editable.

For full type definitions, see references/items-api.md and references/rules-api.md.

Error handling

• Connection refused: The openHAB server is unreachable. Verify the URL and that the server is running.
• 401/403: Authentication failed. Check the API token.
• 404: The item name or rule UID doesn't exist. Use list commands to discover valid names/UIDs.
• 400: Bad request. Verify the command or state value is valid for the item type.

Documentation & Syntax Reference (Local Cloning)

To avoid hallucinating older openHAB Rules DSL or Javascript syntax, you can fetch the official documentation and openhab-js library directly into the workspace. This is the "Context Injection Trick" and provides zero-cost local searching via grep or rg (ripgrep).

Cloning the Reference Material

To set up the local reference materials, execute:

gh repo clone openhab/openhab-js openhab-js-reference
gh repo clone openhab/openhab-docs openhab-docs-reference

Searching the Reference Material

Use grep or rg to find verified syntax before writing .js rules or system configurations.

Examples:

• grep -A 10 -i "getItem" openhab-js-reference/README.md
• rg "Group.*Equipment" openhab-docs-reference/configuration/