Clockwork Canvas CLI

Clockwork Canvas CLI is a command‑line tool designed to manage your desktop wallpaper updates. It automatically fetches beautiful, high‑resolution images from Unsplash based on configurable search queries, organizes them into categories, and updates your wallpaper on a schedule using cron (or APScheduler). Note: This tool is currently compatible only with macOS.

---

Features

• Wallpaper Management:
  Automatically fetch high‑resolution images from Unsplash and update your desktop wallpaper.

• Category & Query Management:
  Organize search queries into categories and cycle through them with ease.

• Scheduling:
  Configure hourly, daily, or custom cron schedules to automate wallpaper updates.

• Configuration Import:
  Easily import a new configuration file to override your current settings.

---

Installation

Before installing, ensure you have Poetry installed.

Using the Makefile Installer

From the project root, run:

make install

This command will:

1. Install Project Dependencies:
   The installer verifies Poetry is installed and runs poetry install to install all required dependencies.

2. Create a Default .env File:
   If a .env file does not exist at the project root, one will be created with a placeholder for the Unsplash API key and the environment set to production.

Note: After installation, you should update your .env file with your actual Unsplash API key. (see below)

---

Obtaining an Unsplash API Key

To use Clockwork Canvas CLI, you must obtain an API key from Unsplash (free, no card needed):

1. Visit Unsplash Developers and log in (or sign up if you don’t already have an account).
2. Create a new application by clicking on "Your Applications" and then "New Application".
3. Once your application is created, you will be provided with an Access Key and a Secret Key.
4. Copy the Access Key and paste it into the UNSPLASH_ACCESS_KEY field in your .env file at the project root.

---

Usage

After installation, you can access the CLI by running:

clockwork-canvas --help

Subcommands

• category:
  Manage wallpaper categories (create, list, update, delete).

• query:
  Manage search queries within a category (add, remove, remove-range, list).

• cron:
  Configure and control the wallpaper update scheduler (set, show, start, stop).

• wallpaper:
  Update your desktop wallpaper immediately.

• config:
  Manage application configuration (e.g., import a new configuration file).

For detailed help on each command, run:

clockwork-canvas <command> --help

For example:

clockwork-canvas category --help

CLI Documentation

For full CLI documentation, please see the CLI Docs.

Importing Example Configuration

To quickly get started, you can import the example configuration provided in this repository. The example_config.json file includes three distinct categories—each with 50 queries—and sets the cron schedule to run hourly. This configuration is a great starting point to see how Clockwork Canvas CLI organizes wallpaper queries and scheduling.

Warning: Importing a new configuration will replace your existing configuration.

To import the example configuration, run:

clockwork-canvas config import example_config.json

Logs

By default, Clockwork Canvas CLI writes its logs to a file named clockwork_canvas.log in the project root. This file contains detailed runtime information such as cron service activity, configuration changes, and error messages.

Running the Tests

You can set the environment variable ENVIRONMENT=testing in your .env file. When set to "testing", the logger configuration suppresses log output (or directs it to a null sink).

To run the project's tests, you have a couple of options:

Using Make

From the project root, simply run:

make tests

This command uses Poetry to run pytest and will execute all tests in the tests directory.

Using Pytest directly

Alternatively, you can run:

poetry run pytest