openhab-rest-cli

A command-line tool for interacting with the openHAB REST API. Read items, send commands, update state, and run rules from your terminal.

Requirements

• Node.js >= 18

Quick Start

Run directly with npx (no install required):

npx openhab-rest-cli --url http://openhab:8080 items list

Or install globally:

npm install -g openhab-rest-cli
openhab-rest-cli items list

Configuration

The CLI resolves connection settings in this order (first wins):

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

Environment variables

export OPENHAB_URL=http://openhab:8080
export OPENHAB_TOKEN=oh.mytoken.secretvalue

Config file

Create ~/.openhab-cli.json:

{
  "url": "http://openhab:8080",
  "token": "oh.mytoken.secretvalue"
}

CLI flags

openhab-rest-cli --url http://openhab:8080 --token oh.mytoken.secretvalue items list

Usage

Items

# List all items
openhab-rest-cli items list

# Filter by type or tags
openhab-rest-cli items list --type Switch
openhab-rest-cli items list --tags Lighting

# Get item details
openhab-rest-cli items get LivingRoom_Light

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

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

# Send a command to an item
openhab-rest-cli items command LivingRoom_Light OFF

Rules

# List all rules
openhab-rest-cli rules list

# Get rule details
openhab-rest-cli rules get my-rule-uid

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

JSON Output

Add --json to any command for machine-readable output:

openhab-rest-cli items list --json
openhab-rest-cli items get MyItem --json | jq .state
openhab-rest-cli rules list --json

Commands Reference

| Command | Description | |---|---| | items list [--type TYPE] [--tags TAGS] | List all items, optionally filtered | | items get <name> | Get details of a single item | | items state <name> | Get the current state of an item | | items update <name> <state> | Update an item's state (PUT) | | items command <name> <command> | Send a command to an item (POST) | | rules list | List all rules | | rules get <uid> | Get details of a single rule | | rules run <uid> | Execute a rule |

Global Options

| Option | Description | |---|---| | --url <url> | openHAB server URL | | --token <token> | API token for authentication | | --config <path> | Path to config file (default: ~/.openhab-cli.json) | | --json | Output results as JSON | | -V, --version | Show version number | | -h, --help | Show help |

Development

git clone https://github.com/alackmann/openhab-rest-cli.git
cd openhab-rest-cli
npm install
npm run build

Test locally:

node dist/index.js --url http://localhost:8080 items list
# or
npx . --url http://localhost:8080 items list

Roadmap

Phase 1 (current) covers items and rules. Future phases will add support for:

• Things management
• Links and channel types
• Add-ons
• Persistence queries
• Sitemaps
• Discovery
• Transformations
• Services configuration

License

MIT