Python CLI Alarm Clock

A lightweight, modular command-line interface (CLI) application for managing alarm schedules (Create, Read/List, Update, Delete) with persistent JSON storage.

Built with Python 3 and Typer.

---

Table of Contents

• Requirements & Setup
• How to Run
• Command Reference
  • 1. Help
  • 2. Create Alarm (create)
  • 3. List Alarms (list)
  • 4. Update Alarm (update)
  • 5. Delete Alarm (delete)
• Storage & Persistence
• Running Automated Tests
• Troubleshooting & Gotchas

---

Requirements & Setup

• Python 3.9+
• Install dependencies:

pip3 install -r requirements.txt

---

How to Run

Important

On macOS, use python3 (the system command is python3, not python). Always execute from the project root directory using the -m module switch:

python3 -m alarm_clock <command>

---

Command Reference

1. Help

Displays all available commands, options, and usage instructions.

python3 -m alarm_clock --help

To see help for a specific command:

python3 -m alarm_clock create --help
python3 -m alarm_clock update --help

---

2. Create Alarm (create)

Creates and persists a new alarm. The application automatically generates an 8-character unique identifier for each alarm.

Syntax:

python3 -m alarm_clock create --time <HH:MM> [--label <TEXT>] [--disabled]

Tip

Important Shell Syntax Rules:

1. Do not type angle brackets <> or square brackets [] literally. They represent placeholder variables in documentation.
2. Always wrap multi-word labels in quotes (e.g. --label "Test Alarm"). Without quotes, the shell passes the second word as an unexpected extra argument.

Examples:

# Correct: multi-word label in quotes
python3 -m alarm_clock create --time 04:30 --label "Test Alarm"

# Correct: short flags
python3 -m alarm_clock create -t 07:30 -l "Morning Run"

# Correct: create as disabled
python3 -m alarm_clock create -t 14:00 -l "Team Standup" --disabled

Output:

Alarm created successfully: ID [a1b2c3d4] at 07:30 (enabled) - 'Morning Workout'

---

3. List Alarms (list)

Displays all stored alarms in a formatted, aligned table sorted chronologically by time (00:00 to 23:59).

Syntax:

python3 -m alarm_clock list

Output:

ID        TIME   STATUS    LABEL
--------  -----  --------  ---------------
a1b2c3d4  07:30  ENABLED   Morning Workout
e5f6g7h8  14:00  DISABLED  Team Standup
9c0b1a2d  18:00  ENABLED   Dinner with friends

If no alarms exist, it outputs: No alarms found. Use 'create' to add one.

---

4. Update Alarm (update)

Updates specific fields on an existing alarm by its 8-character ID. Fields that are not passed remain unchanged.

Syntax:

python3 -m alarm_clock update <ID> [--time <HH:MM>] [--label <TEXT>] [--enable | --disable]

Arguments:

• <ID>: (Required, positional) The 8-character ID of the alarm to modify.

Options:

• -t, --time TEXT: (Optional) New 24-hour time string (HH:MM).
• -l, --label TEXT: (Optional) New label text.
• --enable: (Optional) Sets alarm status to ENABLED.
• --disable: (Optional) Sets alarm status to DISABLED. (Note: --enable and --disable are mutually exclusive).

Examples:

# Update time only
python3 -m alarm_clock update a1b2c3d4 --time 08:00

# Update label and enable alarm
python3 -m alarm_clock update a1b2c3d4 --label "Gym" --enable

# Disable an alarm
python3 -m alarm_clock update a1b2c3d4 --disable

Output:

Alarm [a1b2c3d4] updated successfully: 08:00 (enabled) - 'Gym'

---

5. Delete Alarm (delete)

Permanently deletes an alarm by its ID.

Syntax:

python3 -m alarm_clock delete <ID>

Arguments:

• <ID>: (Required, positional) The 8-character ID of the alarm to delete.

Example:

python3 -m alarm_clock delete a1b2c3d4

Output:

Alarm [a1b2c3d4] (08:00 - 'Gym') deleted successfully.

---

Storage & Persistence

• Default Location: Alarms are automatically saved to:

  ~/.alarms.json
  

  This file is created automatically on the first create invocation. Because it resides in your home directory, your alarms are accessible from any terminal directory.

• Custom Location Override: You can override the storage path by setting the ALARM_CLOCK_FILE environment variable:

  export ALARM_CLOCK_FILE="/path/to/my_alarms.json"
  python3 -m alarm_clock list

---

Running Automated Tests

The project includes a comprehensive suite of 44 automated unit and functional tests covering boundary cases, data model integrity, file I/O, and CLI commands.

To run the complete test suite:

python3 -m unittest discover -s tests -v

To review the itemized test report:

• See TEST_CASES_CHECKED.txt.

---

Troubleshooting & Gotchas

1. zsh: command not found: python

   • Cause: Modern macOS versions only ship with python3.
   • Fix: Use python3 instead of python:

     python3 -m alarm_clock list

2. ImportError: attempted relative import with no known parent package

   • Cause: Running python3 cli.py directly from inside the alarm_clock/ directory.
   • Fix: Change directory back to the repository root and run with -m:

     cd "/Users/apple/Desktop/Python CLI alarm clock"
     python3 -m alarm_clock list

3. ModuleNotFoundError: No module named 'typer'

   • Fix: Install dependencies from requirements.txt:

     pip3 install -r requirements.txt