Metadata-Version: 2.4
Name: ccu-cli
Version: 0.3.1
Summary: CLI tool for interacting with RaspberryMatic/CCU3
Project-URL: Homepage, https://github.com/sussdorff/ccu-cli
Project-URL: Repository, https://github.com/sussdorff/ccu-cli
Project-URL: Issues, https://github.com/sussdorff/ccu-cli/issues
Project-URL: Changelog, https://github.com/sussdorff/ccu-cli/blob/main/CHANGELOG.md
Author: Malte Sussdorff
License-Expression: MIT
License-File: LICENSE
Keywords: ccu,cli,home-automation,homematic,raspberrymatic
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Home Automation
Classifier: Topic :: Utilities
Requires-Python: >=3.14
Requires-Dist: aiohomematic>=2026.4.10
Requires-Dist: click>=8.3.1
Requires-Dist: httpx>=0.28.1
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: rich>=14.2.0
Requires-Dist: tomli>=2.3.0
Description-Content-Type: text/markdown

# ccu-cli

CLI tool for interacting with RaspberryMatic/CCU3 via [aiohomematic](https://github.com/danielperna84/hahomematic).

## Installation

### Local Development

```bash
# 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:

```bash
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:

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

Update an editable install after metadata changes:

```bash
uv tool install --editable . --force
```

Once the package is published, installation becomes:

```bash
uv tool install ccu-cli
```

### Release Workflow

`git-cliff` is configured via [`cliff.toml`](./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`](./pyproject.toml),
refresh the changelog, commit the release, and push a version tag:

```bash
# 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`)

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

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

### Environment variables

```bash
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:

```bash
CCU_HOST=raspberrymatic.local
CCU_USERNAME=admin
CCU_PASSWORD=secret
```

## License

MIT. See [`LICENSE`](./LICENSE).

## Usage

The CLI follows a kubectl-style `resource action` pattern.

### Device Management

```bash
# 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

```bash
# 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

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

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

### System Variables

```bash
# List system variables
ccu sysvar list
```

### Programs

```bash
# 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

```bash
# 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)

```bash
# 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.

```bash
# 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).

```bash
# 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

```bash
# Show CCU info
ccu info
```

## Development

```bash
# Install dev dependencies
uv sync --dev

# Run tests
uv run pytest

# Run CLI directly
uv run ccu --help
```

## License

MIT
