Command-line reference

The school-bell command accepts a JSON object or the path to a JSON file:

$ school-bell CONFIG [OPTIONS]

Use the configuration file explicitly in scripts and services. Examples on this page use /home/pi/schema.json.

Run the scheduler

With no action option, School Bell validates the configuration, initializes the configured integrations and runs the local schedule:

$ school-bell /home/pi/schema.json

Diagnostic and one-off actions

--check

Validate configuration, local WAVE files, OpenHolidays and the public iCalendar feed. It does not play audio, switch GPIO, contact remote bells, start HTTP listeners or run the scheduler. It prints OK, WARNING, ERROR and NOT CONFIGURED results. Exit status zero means all required checks succeeded; non-zero means at least one check failed. Remote SSH and webhook entries are checked structurally only; use the optional Caddy playbook or the procedures in Remote bells and webhooks for DNS and TLS connectivity checks.

--play WAV_KEY

Play one configured local WAVE key and exit. This deliberate manual action bypasses calendar suppression and does not invoke top-level remote trigger destinations.

--test

Exercise real hardware during initialization: activate every configured legacy or key-specific relay output sequentially for one second and test every configured WAVE file. Disconnect the external bell circuit and use a safe audio level first. --check remains non-destructive when both flags are supplied. --test can run alongside school-bell.service when they do not claim the same GPIO pins. If a configured pin is already in use, stop the service before retrying the test.

This is not a remote-bell test mode. Normal initialization and scheduling continue after the local tests. A legacy top-level SSH trigger is therefore checked with remote aplay --help during startup, just as in a normal run. Configured schedules can subsequently invoke those SSH targets, and pressing a configured manual button can invoke its SSH or webhook remote_bells. Combine --test with --check when only non-operational validation is intended; --check takes precedence.

--debug

Enable verbose local logging. It can reveal hostnames and operational details, so retain logs according to local policy.

Generate examples and inspect the version

--demo-config

Print a complete example configuration and exit. Redirect it to a file and remove unused optional integrations before the first run.

$ school-bell --demo-config > /home/pi/schema.json

--demo-service

Print a basic systemd unit for the current user and exit. Managed installations should use the supplied Ansible playbooks instead.

--version

Print the installed School Bell version and exit.

--help

Print the authoritative option summary for the installed version.

Self-update

--update [REVISION] installs School Bell from GitHub using pip and exits. With no revision it follows main. This is retained for simple, unmanaged installations, but it does not provide the configuration-preserving checks, pinning and controlled rollout of Deploying with Ansible.

Do not use --update on an Ansible-managed production node. Select an exact tested release or commit with ansible/update.yml instead.

GPIO configuration

Relay pins are configured through legacy buzz_gpio/buzz_active_high or the key-specific relays list in JSON. There is no command-line GPIO override. This keeps the validated configuration, runtime behavior and reported configuration hash aligned. See GPIO, relays and manual button for wiring and testing.