---
url: /mod/cron.md
---
# x cron

Lightweight cron job scheduler with add, remove, list, and match testing.

Jobs are isolated by namespace with per-namespace timezone support.

Supports standard cron time format (min hour day month dow).

Each job is stored as a directory containing the cron pattern, cmd script,

and optional description.

## Examples

Example: Add a described job that runs every 5 minutes

```sh
x cron add --name myjob --desc "say hello" "*/5 * * * *" "echo hello"
```

Example: Add a one-time job

```sh
x cron add --once --name greeting "0 9 * * *" "echo good morning"
```

Example: List all jobs

```sh
x cron ls
```

Example: Remove a job

```sh
x cron rm myjob
```

Example: Test if current time matches a cron pattern

```sh
x cron match "*/5 * * * *"
```

Example: Test if a specific time matches a cron pattern

```sh
x cron match "*/5 * * * *" "30 8 16 4 4"
```

Example: Set scheduling timezone for the current namespace

```sh
x cron tz Asia/Shanghai
```

Example: Start the cron daemon

```sh
x cron service start
```

Example: Debug daemon for a namespace in foreground

```sh
x cron run --ns mynamespace
```

Example: Manually trigger a one-time job run

```sh
x cron runonce
```

Example: Execute a specific job directly for testing

```sh
x cron exec myjob
```

Example: View the latest execution details for a job

```sh
x cron history myjob
```

Example: View execution details for a specific timestamp

```sh
x cron history myjob 1715673705
```

## Sub Commands

| Name | Description |
| ------- | ------- |
| [x cron add](/mod/cron/add.md) | Add a cron job |
| [x cron rm](/mod/cron/rm.md) | Remove a job by name |
| [x cron ls](/mod/cron/ls.md) | List all jobs in the current namespace (TSV: name pattern description) |
| [x cron match](/mod/cron/match.md) | Test if a time matches a cron pattern (uses current time by default) |
| [x cron tz](/mod/cron/tz.md) | Configure the timezone for job scheduling |
| [x cron run](/mod/cron/run.md) | Run the cron daemon in the foreground (loop, check and run matching jobs every minute) |
| [x cron runonce](/mod/cron/runonce.md) | Execute all jobs matching the current time once (no loop) |
| [x cron history](/mod/cron/history.md) | View execution details for a cron job (shows latest if timestamp omitted) |
| [x cron exec](/mod/cron/exec.md) | Execute a specific job's command directly (ignoring cron time match, for testing) |
| [x cron service](/mod/cron/service.md) | Manage the cron daemon |