> For the complete documentation index, see [llms.txt](https://seanime.gitbook.io/seanime-extensions/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://seanime.gitbook.io/seanime-extensions/plugins/ui/cron.md).

# Cron

Schedule recurring UI-context jobs with cron expressions.

`ctx.cron` lets UI plugins register recurring jobs.

## Permissions

{% hint style="warning" %}
`cron` permission is required.
{% endhint %}

<pre class="language-json"><code class="lang-json">{
  //...
  "plugin": {
    "permissions": {
<strong>      "scopes": ["cron"]
</strong>    }
  }
}
</code></pre>

## Quick example

```typescript
$ui.register((ctx) => {
    ctx.cron.add("refresh-anime-cache", "*/15 * * * *", () => {
        console.log("refreshing anime cache")
    })

    ctx.cron.start()
})
```

## Expressions

Seanime accepts either one of the supported macros or a five-part cron expression:

`minute hour day-of-month month day-of-week`

Supported segment formats:

* `*`
* `1-5`
* `*/10`
* `1-30/5`
* `1,2,10-20/2`

Supported macros:

* `@yearly` / `@annually`
* `@monthly`
* `@weekly`
* `@daily` / `@midnight`
* `@hourly`
* `@30min`
* `@15min`
* `@10min`
* `@5min`

## Methods

### add

`ctx.cron.add(jobId, cronExpr, callback)`

Registers a job.

If the same `jobId` already exists, Seanime replaces it.

**Parameters:**

* `jobId`: String - Unique job identifier.
* `cronExpr`: String - Cron macro or five-part expression.
* `callback`: Function - Job body.

### remove

`ctx.cron.remove(jobId)`

Removes one job by ID.

### removeAll

`ctx.cron.removeAll()`

Removes every registered job.

### total

`ctx.cron.total()`

Returns the number of registered jobs.

### start

`ctx.cron.start()`

Starts the scheduler.

Calling `start()` again restarts it.

### stop

`ctx.cron.stop()`

Stops the scheduler.

### hasStarted

`ctx.cron.hasStarted()`

Returns whether the scheduler is currently running.

## Notes

* Adding jobs does not start the scheduler automatically.
* Jobs run asynchronously when they become due.