AI agent skill for managing the [Cronicle](https://github.com/jhuckaby/Cronicle) timed task scheduling system via its REST API. Provides 14 operations covering the full lifecycle of scheduled events and jobs, plus one-shot task support via Chain Reaction.
## Overview
This skill enables AI agents to programmatically manage a Cronicle scheduler — creating cron-like timed events, running jobs on demand, monitoring execution status, viewing history, and controlling the scheduler itself.
Trigger the skill by mentioning Cronicle, scheduled tasks, cron jobs, timed events, or scheduler management. The agent will read `SKILL.md` and execute operations via the client script.
### 4. Direct CLI Usage
```bash
# List all scheduled events
python scripts/cronicle_client.py get_schedule
# Create an HTTP request event that runs every 5 minutes
| `CRONICLE_API_KEY` | Yes | 32-character hex API key |
| `CRONICLE_DEFAULT_CATEGORY` | For create | Default category ID for new events |
| `CRONICLE_DEFAULT_TARGET` | For create | Default target server or group ID |
| `CRONICLE_DEFAULT_PLUGIN` | For create | Default plugin ID (`urlplug` or `shellplug`) |
## MCP Counterpart
This skill mirrors the [bos-crobicle-mcp](https://github.com/anomalyco/opencode) MCP server, which provides the same 14 operations plus a native `create_one_shot_event` tool via structured function calling. The skill approach uses direct CLI/Python invocation while the MCP approach uses typed tool signatures managed by the MCP protocol.
## References
-[Cronicle Official Docs](https://github.com/jhuckaby/Cronicle)
-[Cronicle API Reference](https://github.com/jhuckaby/Cronicle/blob/master/docs/APIReference.md)
-[SKILL.md](SKILL.md) — Core skill instructions
-[Event Fields Reference](references/event-fields.md) — Complete event data format
description:Manages Cronicle timed task scheduler via REST API. Use when the user needs to list/create/update/delete scheduled events, run jobs on demand, monitor job status, view history, abort running jobs, or enable/disable the scheduler. Triggers include mentions of Cronicle, scheduled tasks, cron jobs, timed events, or scheduler management.
---
# Cronicle Scheduler Management
Manages the Cronicle timed task scheduling system via its REST API. Provides 14 operations for full lifecycle management of scheduled events and jobs.
## Setup
1. Copy `.env.example` to `.env` in the skill directory (`managing-cronicle-scheduler/`):
| **get_event_history** | `python scripts/cronicle_client.py get_event_history --id evt123` | Completed jobs for one event. Supports `--offset` and `--limit`. |
| **get_history** | `python scripts/cronicle_client.py get_history` | Global completed jobs. Supports `--offset` and `--limit`. |
### Scheduler Control
| Operation | CLI Example | Description |
|-----------|------------|-------------|
| **get_master_state** | `python scripts/cronicle_client.py get_master_state` | Check if scheduler is enabled (`enabled: 1` or `0`). |
| **update_master_state** | `python scripts/cronicle_client.py update_master_state --enabled 1` | Enable (`--enabled 1`) or disable (`--enabled 0`) the scheduler. |
## One-Shot Tasks
Cronicle has no native one-shot task support. For non-recurring tasks like "notify me at 3pm to buy groceries", use **Chain Reaction self-cleanup**:
1. Create the task event with exact `timing`
2. Create a cleanup event (`urlplug` calling `update_event` against the task)
3. Link them: `update_event(task_id, chain=cleanup_id)`
At the scheduled time: task runs → completes → chain triggers cleanup → cleanup disables task via API.
Full workflow with time expression mapping: [one-shot-tasks.md](references/one-shot-tasks.md)
## Event Data Fields
When creating/updating events, pass additional fields via `-f key=value` (CLI) or the `extra` dict (Python). Key fields:
- `plugin` — **must use plugin ID**: `urlplug` (HTTP Request) or `shellplug` (Shell Script)
- `params` — plugin-specific parameters (see [plugin-params.md](references/plugin-params.md)):
Complete reference of all properties in the Cronicle event object, from the [official API docs](https://github.com/jhuckaby/Cronicle/blob/master/docs/APIReference.md#event-data-format). Pass these as `-f key=value` in CLI or include in the `extra` dict when using the Python API.
## Identity & Status
| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique ID assigned when the event was first created |
| `title` | string | Display name shown on Schedule Tab, reports, and emails (required for create) |
| `enabled` | 0/1 | Whether the event is active in the scheduler |
| `category` | string | Category ID the event is assigned to |
| `plugin` | string | Plugin ID that runs the job: `urlplug` (HTTP Request), `shellplug` (Shell Script) |
| `target` | string | Server Group ID or individual server hostname |
| `algo` | string | Algorithm for picking a server from the target group: `round_robin`, `random`, `least_cpu`, `least_mem` |
| `created` | number | Date/time of initial creation, in Epoch seconds |
| `modified` | number | Date/time of last modification, in Epoch seconds |
| `username` | string | Username of user who created the event (if created in UI) |
| `api_key` | string | API Key of the application that created the event (if created via API) |
## Scheduling
| Field | Type | Description |
|-------|------|-------------|
| `timing` | object | Cron-like schedule. Omit for on-demand, empty `{}` for every minute. See [Timing Object](#timing-object-format) below. |
| `web_hook` | string | URL to ping on job start and completion |
| `chain` | string | Event ID to launch when job completes successfully |
| `chain_error` | string | Event ID to launch when job fails |
| `notes` | string | Free-text notes, included in email notifications |
## Plugin Parameters
| Field | Type | Description |
|-------|------|-------------|
| `params` | object | Plugin-specific parameters. See [plugin-params.md](plugin-params.md) for full details per plugin. |
## Timing Object Format
Cron-like schedule where each property is an array of numbers. Omitted properties = all values (like `*` in cron). Empty object `{}` means every minute.
| Property | Range | Example | Description |
|----------|-------|---------|-------------|
| `years` | YYYY | `[2026]` | One or more years |
| `months` | 1–12 | `[1, 4, 7, 10]` | January is 1, December is 12 |
Cronicle has no native one-shot task support. Use **Chain Reaction** to simulate it: the task event links a cleanup event that disables the task after one execution.
## Chain Reaction Self-Cleanup Workflow
```
Step 1: Create task event → get task_id
Step 2: Create cleanup event (urlplug that calls update_event API on task_id)
Step 3: Link cleanup via chain: update_event(task_id, chain=cleanup_id)
The cleanup event will auto-disable the task event (sets `enabled=0`). The task and cleanup events remain in the schedule (disabled), preserving history. To fully remove, run:
Plugin ID: `shellplug`. Executes a shell script on the target server.
### Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `script` | string | `"#!/bin/sh\n\n# Enter your shell script code here\n"` | Shell script content. Must start with a shebang line (e.g., `#!/bin/sh`, `#!/bin/bash`). |
| `json` | any | — | If set, child process JSON output is passed to Cronicle as real-time job updates (progress, HTML, etc.). |
| `annotate` | any | — | If set, non-JSON output lines get timestamp annotations like `[YYYY-MM-DD HH:MI:SS]`. |
**Progress reporting:** Output a line matching `\d+%` (e.g., `50%`) to report progress. The number is mapped to 0.0–1.0.
**Child JSON updates:** When `json` is enabled, the child process can emit JSON to stdout to update the job. Supported keys include:
-`progress` — number 0.0–1.0
-`html` — `{title: "...", content: "<pre>...</pre>"}` for custom job report
-`complete`, `code`, `description` — to signal job completion
**Placeholders:** The full job object is sent to the child process on stdin, accessible via standard shell input. Events set with `run_event` pass custom params via `event_data`.
Additional generic parameters (timeout, resource limits, etc.) are set at the event level, not inside `params`.
### Examples
**Simple shell command:**
```json
{
"params":{
"script":"#!/bin/sh\n\necho \"Hello from Cronicle at $(date)\"\n"
