Cron System

Human includes a cron-like scheduler that lets scheduled commands run on a recurring basis. Jobs are stored in a JSON crontab file and executed by the service loop when the gateway is running.

CLI commands

The cron CLI manages the crontab file at ~/.human/crontab.json:

human cron list                      # List all scheduled jobs
human cron add "<schedule>" <command>  # Add a job
human cron remove <id>               # Remove a job by ID

Example:

human cron add "0 9 * * *" "Check email and summarize"
human cron add "*/15 * * * *" echo "Heartbeat"
human cron list
human cron remove 1

Crontab file format

Jobs are persisted in ~/.human/crontab.json as a JSON array:

[
  {
    "id": "1",
    "schedule": "0 9 * * *",
    "command": "Check email and summarize",
    "enabled": true
  }
]

Cron expression format

Standard 5-field cron syntax:

┌───────── minute (0-59)
│ ┌─────── hour (0-23)
│ │ ┌───── day of month (1-31)
│ │ │ ┌─── month (1-12)
│ │ │ │ ┌─ day of week (0-6, Sun=0)
│ │ │ │ │
* * * * *

Example schedules

| Expression | Schedule | | ---------------- | ------------------------- | | 0 9 * * * | Every day at 9:00 AM | | */15 * * * * | Every 15 minutes | | 0 0 * * 1 | Every Monday at midnight | | 0 8,17 * * 1-5 | 8 AM and 5 PM on weekdays |

Configuration

Cron behavior is configured in ~/.human/config.json under the cron key:

{
  "cron": {
    "enabled": true,
    "interval_minutes": 30,
    "max_run_history": 50
  }
}

| Field | Description | Default | | ------------------ | -------------------------------------- | ------- | | enabled | Enable cron job execution | false | | interval_minutes | How often the scheduler ticks (1–1440) | 30 | | max_run_history | Max run records kept per job (0–10000) | 50 |

Gateway control protocol

When running the gateway (human gateway or human service-loop), the WebSocket control protocol exposes additional cron methods:

| Method | Description | | ------------- | ---------------------- | | cron.list | List scheduled jobs | | cron.add | Add a job | | cron.remove | Remove a job | | cron.run | Manually trigger a job |

Use these from the Control UI or any client that connects to the gateway WebSocket.

Build requirement

Cron support requires HU_HAS_CRON (enabled by default). Without it, the cron command and control methods are unavailable.