📝 Scripting and Custom Automation

CoolerControl exposes a full REST API that the Desktop and Web UI use to communicate with the daemon. You can use the same API (or the official CLI) to build automations, integrate with other tools, or script routine tasks.

Options at a glance

• The official CLI/TUI: cctv
  • Great for shell scripts, cron/systemd timers, hooks, and quick terminal control.
  • Try cctv --help to see available commands and flags.
• The HTTP API: OpenAPI Explorer
  • Browse endpoints and schemas, and try requests directly from the browser.
  • Copy ready-made curl or client snippets from the explorer for your language of choice.

TIP

For scripts and automations, use an Access Token rather than the admin password. Tokens are stateless, can have expiry dates, and can be revoked individually without changing your password. For remote access, see Headless Servers and Remote Access.

Choosing the right tool

Tool	Best for	Requires
cctv CLI	Shell scripts, cron/systemd timers, one-liners	cctv installed
REST API	Custom integrations, Python/JS code, Home Assistant	Auth token
Plugins	New device types, persistent background services	Plugin development
Power Profile Sync	Auto-switching Modes with system power profiles	tuned/tuned-ppd

Rule of thumb: Start with cctv. Move to the REST API if you need data cctv doesn't expose. Write a plugin only if you need to add a new device type.

Common cctv examples

List available Modes, then activate one:

cctv --list-modes
cctv --activate-mode Quiet

Dump information about the system to stdout as json:

cctv --dump

These commands can be used in any automation context (udev hooks, tuned scripts, cron/systemd timers, etc.). For a more concrete example, see Synchronizing CoolerControl with Power Profiles.

Using the REST API

Open the OpenAPI page to discover endpoints, their request/response shapes, and authorization requirements. From there you can:

• Use the “Try it out” feature to prototype requests against your local daemon.
• Copy curl examples or language-specific snippets to your codebase.

Notes:

• The daemon binds to the loopback interface by default. For remote access, prefer SSH tunneling or a TLS reverse proxy.
• If you enable access protection, supply the appropriate credentials/headers as shown in the OpenAPI explorer and Access Protection.

REST API Code example

You can find a minimal Python example in the CoolerControl repository:

• scripts/cc.py in the source repository

You can use this as a starting point to build richer automations and integrations.

See Also

• cctv CLI - Full reference for the official command-line tool
• REST API - Browse all available endpoints
• Plugins - Extend CoolerControl with custom device support
• Power Profile Sync - Auto-switch Modes with system power profiles
• Access Protection - Generate access tokens for scripts and integrations