ccu-cli

CLI tool for interacting with RaspberryMatic/CCU3 via aiohomematic.

Installation

Local Development

# Clone repository
git clone https://github.com/sussdorff/ccu-cli.git
cd ccu-cli

# Install project dependencies
uv sync

# Run from the checkout
uv run ccu --help

Global Tool Installation

Install ccu once and call it from any directory:

cd /path/to/ccu-cli

# Install as an editable global uv tool
uv tool install --editable .

# Show the directory that must be on your PATH
uv tool dir --bin

If ccu is not found yet, add the tool bin directory to your shell config:

export PATH="$(uv tool dir --bin):$PATH"

Update an editable install after metadata changes:

uv tool install --editable . --force

Once the package is published, installation becomes:

uv tool install ccu-cli

Release Workflow

git-cliff is configured via cliff.toml and accepts both the existing SemVer tags and future CalVer tags like v2026.4.15.

PyPI publishing is configured via GitHub Trusted Publishing. Create the pending publisher in PyPI with:

• Project name: ccu-cli
• Owner: sussdorff
• Repository name: ccu-cli
• Workflow name: release.yml
• Environment name: pypi

For a release, set the package version in pyproject.toml, refresh the changelog, commit the release, and push a version tag:

# Refresh the unreleased changelog section
uv run git-cliff --unreleased --prepend CHANGELOG.md

# Build sdist + wheel
uv build

# Optional: validate the built artifacts locally
uv publish --dry-run dist/*

# Commit the release metadata
git add CHANGELOG.md pyproject.toml uv.lock
git commit -m "chore(release): prepare v0.3.1"

# Push the release tag to trigger GitHub Trusted Publishing
git tag v0.3.1
git push origin main --follow-tags

Configuration

Configuration is loaded in the following order (later sources override earlier):

1. XDG config: $XDG_CONFIG_HOME/ccu-cli/config.toml (default: ~/.config/ccu-cli/config.toml)
2. Environment variables
3. Local .env file (for development)

Config file (~/.config/ccu-cli/config.toml)

[ccu]
host = "raspberrymatic.local"
https = false

# Optional authentication
# username = "admin"
# password = "secret"

Environment variables

export CCU_HOST="raspberrymatic.local"
export CCU_HTTPS="false"
export CCU_USERNAME="admin"
export CCU_PASSWORD="secret"

Local .env file (development)

For local development, create a .env file in the project root:

CCU_HOST=raspberrymatic.local
CCU_USERNAME=admin
CCU_PASSWORD=secret

License

MIT. See LICENSE.

Usage

The CLI follows a kubectl-style resource action pattern.

Device Management

# List all devices
ccu device list

# Show device details
ccu device get <address>

# Rename a device
ccu device rename <address> <new-name>

# Rename a device and all channels to name:channel_no
ccu device rename --include-channels <address> <new-name>

# Show channel configuration (MASTER paramset)
ccu device config <address>:<channel>

# Refresh hub data (programs, sysvars) from CCU
ccu device refresh

Channel Management

# Rename a channel by ReGa object id
ccu channel rename <channel-id> <new-name>

# Rename a channel by exact channel address
ccu channel rename <address>:<channel> <new-name>

Datapoints

# Read a datapoint value
ccu datapoint get <address>:<channel>/<datapoint>

# Set a datapoint value
ccu datapoint set <address>:<channel>/<datapoint> <value>

System Variables

# List system variables
ccu sysvar list

Programs

# List programs
ccu program list

# Show program details
ccu program get <id-or-name>

# Run a program
ccu program run <id-or-name>

# Enable/disable a program
ccu program enable <id-or-name>
ccu program disable <id-or-name>

# Delete a program
ccu program delete <id-or-name> [--yes]

Rooms

# List rooms
ccu room list

# Show room details and devices
ccu room get <room-id>

# Create a room
ccu room create <name>

# Rename a room
ccu room rename <room-id> <new-name>

# Delete a room
ccu room delete <room-id> [--yes]

# Manage devices in rooms
ccu room add-device <room-id> <channel-id>
ccu room remove-device <room-id> <channel-id>
ccu room devices <room-id>

Device Links (Direktverknüpfungen)

# List all links (optionally filter by address)
ccu link list [-a <address>]

# Show link details
ccu link get <sender> <receiver>

# Create a link
ccu link create <sender> <receiver> [--name "Link Name"]

# Delete a link
ccu link delete <sender> <receiver> [--yes]

# Get link parameters (queries both sender and receiver sides)
ccu link config get <sender> <receiver>

# Set link parameters (default: receiver/actuator side)
ccu link config set <sender> <receiver> PARAM=value [PARAM2=value2 ...]

# Set parameters on sender/button side
ccu link config set --side sender <sender> <receiver> PARAM=value

Heating Groups

Inspect existing heating groups from the CCU VirtualDevices//groups interface. group get also resolves the configured member devices via CCU JSON-RPC.

# List existing heating groups
ccu group list

# Show details, member devices, and channels for a group
ccu group get <group-address>

# Delete a group
ccu group delete <group-address> [--yes]

Examples of group addresses are INT0000003 or INT0000001.

Note: creating heating groups is not implemented yet. The current CLI support focuses on discovering and inspecting existing groups, plus deleting them.

Thermostat Schedules (Wochenprogramme)

Manage heating profiles for HomeMatic thermostats (HM-TC-IT-WM-W-EU, HM-CC-RT-DN).

# Show current heating schedule
ccu schedule get <address>
ccu schedule get <address> --day mon
ccu schedule get <address> --profile 2

# Set a simple schedule (one heating period per day)
ccu schedule set-simple <address> --start 05:00 --end 22:00
ccu schedule set-simple <address> --start 06:00 --end 20:00 --comfort 21 --lowering 17
ccu schedule set-simple <address> --start 05:00 --end 22:00 --day mon --day tue --day wed

# Set constant temperature (no night setback)
ccu schedule set-constant <address> --temp 21
ccu schedule set-constant <address> --temp 21 --day sat --day sun

# Activate a specific profile (P1, P2, or P3)
ccu schedule activate <address> 1

Schedule structure:

• Each thermostat has 3 profiles (P1, P2, P3)
• Each profile has up to 13 time slots per day
• WEEK_PROGRAM_POINTER determines the active profile (0=P1, 1=P2, 2=P3)

Other Commands

# Show CCU info
ccu info

Development

# Install dev dependencies
uv sync --dev

# Run tests
uv run pytest

# Run CLI directly
uv run ccu --help

License

MIT