<!--
hoody-cron Subskill (cli)
Auto-generated by Hoody Skills Generator
Generated: 2026-05-06T20:43:30.291Z
Model: mimo-v2.5-pro + fixer:mimo-v2.5-pro
Mode: cli


Tokens: 6009

DO NOT EDIT MANUALLY - Changes will be overwritten on next generation
-->

# hoody-cron Subskill

## Overview

### What is hoody-cron?

hoody-cron is a managed cron job scheduling service within the Hoody ecosystem. It provides reliable, container-aware job scheduling with built-in enable/disable controls. The service manages user-specific crontab configurations and individual cron entries through a RESTful API accessible via the `hoody cron` CLI commands.

### When to Use hoody-cron

Use hoody-cron when you need to:

- **Schedule recurring tasks** — Run commands on fixed schedules (hourly, daily, weekly, etc.)
- **Manage maintenance windows** — Enable/disable jobs without deleting configurations
- **Automate cleanup** — Set auto-expiration for temporary scheduled tasks
- **Coordinate container operations** — Schedule tasks targeting specific Hoody containers
- **Implement time-based workflows** — Trigger batch processing, backups, or monitoring at specific intervals

### How It Fits Into Hoody Philosophy

hoody-cron embodies Hoody's managed service principles:

- **Container-scoped operations** — All commands target containers via `-c <container-id>` or `HOODY_CONTAINER` env var
- **CLI-first interface** — No direct HTTP calls; use `hoody cron` commands exclusively
- **Structured output** — Use `-o json` for machine-readable responses
- **Authentication integration** — Leverages Hoody's unified auth system (`hoody auth login`, `--token`, or `HOODY_TOKEN`)

### Key Concepts

| Concept | Description |
|---------|-------------|
| **Crontab** | A complete cron configuration file for a user |
| **Entry** | An individual scheduled job within a crontab |
| **Schedule** | Standard cron expression (e.g., `0 2 * * *` for daily at 2 AM) |
| **Command** | The shell command to execute when the job triggers |
| **User** | The owner of the crontab/entries (required for all operations) |

---

## Common Workflows

### Workflow 1: Health Check and Service Verification

Before performing any cron operations, verify the service is healthy.

**Step 1: Check service health**

```
hoody cron health -c my-container
```

**Expected response:**

```
{
  "status": "ok"
}
```

**Step 2: List all crontabs to verify connectivity**

```
hoody cron list -c my-container -o json
```

**Expected response:**

```
[
  "user1",
  "user2",
  "deploy-bot"
]
```

**Verification:** If health check fails, verify container is running with `hoody containers status -c my-container`.

---

### Workflow 2: Create a New Scheduled Job

**Scenario:** Schedule a daily database backup at 2:30 AM for user `app-service`.

**Step 1: Create the cron entry**

```
hoody cron create app-service -c my-container --command "/usr/local/bin/backup-db.sh" --schedule "30 2 * * *"
```

**Expected response:**

```
{
  "id": "abc123def456",
  "command": "/usr/local/bin/backup-db.sh",
  "schedule": "30 2 * * *",
  "enabled": true
}
```

**Step 2: Verify the entry was created**

```
hoody cron get app-service abc123def456 -c my-container -o json
```

**Expected response:**

```
{
  "id": "abc123def456",
  "command": "/usr/local/bin/backup-db.sh",
  "schedule": "30 2 * * *",
  "enabled": true
}
```

**Step 3: List all entries for the user to confirm**

```
hoody cron list app-service -c my-container -o json
```

**Expected response:**

```
[
  {
    "id": "abc123def456",
    "command": "/usr/local/bin/backup-db.sh",
    "schedule": "30 2 * * *",
    "enabled": true
  }
]
```

---

### Workflow 3: Retrieve and Inspect a User's Crontab

**Step 1: Get the full crontab for a user**

```
hoody cron get app-service -c my-container -o json
```

**Expected response:**

```
{
  "user": "app-service",
  "crontab": "30 2 * * * /usr/local/bin/backup-db.sh\n0 */6 * * * /usr/local/bin/cleanup-temp.sh"
}
```

**Step 2: List individual entries for detailed inspection**

```
hoody cron list app-service -c my-container -o json
```

**Expected response:**

```
[
  {
    "id": "abc123def456",
    "command": "/usr/local/bin/backup-db.sh",
    "schedule": "30 2 * * *",
    "enabled": true
  },
  {
    "id": "xyz789ghi012",
    "command": "/usr/local/bin/cleanup-temp.sh",
    "schedule": "0 */6 * * *",
    "enabled": true
  }
]
```

---

### Workflow 4: Update an Existing Cron Entry

**Scenario:** Change the backup schedule from 2:30 AM to 3:00 AM.

**Step 1: Update the entry**

```
hoody cron update app-service abc123def456 -c my-container --schedule "0 3 * * *"
```

Note: The update command also accepts `--enabled` flag to enable or disable the entry (e.g., `--enabled false`).

**Expected response:**

```
{
  "id": "abc123def456",
  "command": "/usr/local/bin/backup-db.sh",
  "schedule": "0 3 * * *",
  "enabled": true
}
```

**Step 2: Verify the update**

```
hoody cron get app-service abc123def456 -c my-container -o json
```

**Expected response:**

```
{
  "id": "abc123def456",
  "command": "/usr/local/bin/backup-db.sh",
  "schedule": "0 3 * * *",
  "enabled": true
}
```

---

### Workflow 5: Delete a Cron Entry

**Scenario:** Remove the temporary cleanup job that is no longer needed.

**Step 1: Delete the entry (requires confirmation)**

```
hoody cron delete app-service xyz789ghi012 -c my-container --yes
```

**Expected response:**

```
{
  "deleted": true,
  "id": "xyz789ghi012"
}
```

**Step 2: Verify deletion by listing remaining entries**

```
hoody cron list app-service -c my-container -o json
```

**Expected response:**

```
[
  {
    "id": "abc123def456",
    "command": "/usr/local/bin/backup-db.sh",
    "schedule": "0 3 * * *",
    "enabled": true
  }
]
```

---

### Workflow 6: Replace Entire Crontab

**Scenario:** Bulk update all cron jobs for a user with a new configuration.

**Step 1: Replace the crontab**

```
hoody cron replace app-service -c my-container --crontab "0 3 * * * /usr/local/bin/backup-db.sh
0 0 * * 0 /usr/local/bin/weekly-report.sh"
```

**Expected response:**

```
{
  "user": "app-service",
  "crontab": "0 3 * * * /usr/local/bin/backup-db.sh\n0 0 * * 0 /usr/local/bin/weekly-report.sh"
}
```

**Step 2: Verify the replacement**

```
hoody cron get app-service -c my-container -o json
```

**Expected response:**

```
{
  "user": "app-service",
  "crontab": "0 3 * * * /usr/local/bin/backup-db.sh\n0 0 * * 0 /usr/local/bin/weekly-report.sh"
}
```

---

## Advanced Operations

### Multi-Container Cron Orchestration

**Scenario:** Schedule coordinated jobs across multiple containers.

**Step 1: Create backup job on primary container**

```
hoody cron create app-service -c primary-container --command "/scripts/backup-primary.sh" --schedule "0 1 * * *"
```

**Expected response:**

```
{
  "id": "primary-job-001",
  "command": "/scripts/backup-primary.sh",
  "schedule": "0 1 * * *",
  "enabled": true
}
```

**Step 2: Create sync job on secondary container (runs 30 minutes later)**

```
hoody cron create app-service -c secondary-container --command "/scripts/sync-from-primary.sh" --schedule "30 1 * * *"
```

**Expected response:**

```
{
  "id": "secondary-job-001",
  "command": "/scripts/sync-from-primary.sh",
  "schedule": "30 1 * * *",
  "enabled": true
}
```

**Step 3: Verify both containers have correct schedules**

```
hoody cron list app-service -c primary-container -o json
```

```
hoody cron list app-service -c secondary-container -o json
```

---

### Error Recovery: Handling Failed Job Creation

**Scenario:** Job creation fails due to invalid schedule syntax.

**Step 1: Attempt creation with invalid cron expression**

```
hoody cron create app-service -c my-container --command "/scripts/task.sh" --schedule "invalid"
```

**Expected error response:**

```
{
  "error": "Invalid cron expression",
  "code": "INVALID_SCHEDULE"
}
```

**Step 2: Correct the schedule and retry**

```
hoody cron create app-service -c my-container --command "/scripts/task.sh" --schedule "*/15 * * * *"
```

**Expected response:**

```
{
  "id": "recovery-job-001",
  "command": "/scripts/task.sh",
  "schedule": "*/15 * * * *",
  "enabled": true
}
```

**Step 3: Verify successful creation**

```
hoody cron get app-service recovery-job-001 -c my-container -o json
```

---

### Bulk Operations: Managing Multiple Entries

**Scenario:** Disable all jobs for a user during maintenance window.

**Step 1: List all current entries**

```
hoody cron list app-service -c my-container -o json
```

**Expected response:**

```
[
  {
    "id": "job-001",
    "command": "/scripts/task1.sh",
    "schedule": "0 * * * *",
    "enabled": true
  },
  {
    "id": "job-002",
    "command": "/scripts/task2.sh",
    "schedule": "30 * * * *",
    "enabled": true
  }
]
```

**Step 2: Update each entry to disable (repeat for each job ID)**

```
hoody cron update app-service job-001 -c my-container --enabled false
```

```
hoody cron update app-service job-002 -c my-container --enabled false
```

**Step 3: Verify all jobs are disabled**

```
hoody cron list app-service -c my-container -o json
```

**Expected response:**

```
[
  {
    "id": "job-001",
    "command": "/scripts/task1.sh",
    "schedule": "0 * * * *",
    "enabled": false
  },
  {
    "id": "job-002",
    "command": "/scripts/task2.sh",
    "schedule": "30 * * * *",
    "enabled": false
  }
]
```

---

### Performance Considerations

| Consideration | Recommendation |
|---------------|----------------|
| **Polling frequency** | Avoid schedules more frequent than `*/5 * * * *` (every 5 minutes) |
| **Command execution time** | Ensure commands complete within the schedule interval |
| **Concurrent jobs** | Stagger schedules to avoid resource contention |
| **Container resources** | Monitor CPU/memory usage with `hoody containers stats -c <container-id>` |
| **Log management** | Implement log rotation for jobs that generate significant output |

---

## Quick Reference

### Essential Commands

| Command | Description | Required Parameters |
|---------|-------------|---------------------|
| `hoody cron health` | Check service health | `-c <container-id>` |
| `hoody cron list` | List all crontabs | `-c <container-id>` |
| `hoody cron get <user>` | Get user's crontab | `-c <container-id>` |
| `hoody cron replace <user>` | Replace user's crontab | `-c <container-id>`, `--crontab` |
| `hoody cron list <user>` | List user's entries | `-c <container-id>` |
| `hoody cron create <user>` | Create new entry | `-c <container-id>`, `--command`, `--schedule` |
| `hoody cron get <user> <id>` | Get specific entry | `-c <container-id>` |
| `hoody cron update <user> <id>` | Update entry | `-c <container-id>` |
| `hoody cron delete <user> <id>` | Delete entry | `-c <container-id>`, `--yes` |

### Common Cron Schedules

| Schedule | Description |
|----------|-------------|
| `* * * * *` | Every minute |
| `*/5 * * * *` | Every 5 minutes |
| `0 * * * *` | Every hour |
| `0 0 * * *` | Daily at midnight |
| `0 2 * * *` | Daily at 2 AM |
| `0 0 * * 0` | Weekly on Sunday |
| `0 0 1 * *` | Monthly on the 1st |

### Typical Response Formats

**Single entry response:**

```
{
  "id": "abc123",
  "command": "/path/to/script.sh",
  "schedule": "0 2 * * *",
  "enabled": true
}
```

**List entries response:**

```
[
  {
    "id": "abc123",
    "command": "/path/to/script.sh",
    "schedule": "0 2 * * *",
    "enabled": true
  }
]
```

**Crontab response:**

```
{
  "user": "app-service",
  "crontab": "0 2 * * * /path/to/script.sh"
}
```

**Delete response:**

```
{
  "deleted": true,
  "id": "abc123"
}
```

### Environment Variables

| Variable | Description |
|----------|-------------|
| `HOODY_CONTAINER` | Default container ID (alternative to `-c` flag) |
| `HOODY_TOKEN` | API authentication token |

### CLI Aliases

| Command | Aliases |
|---------|---------|
| `hoody cron create` | `new`, `add` |
| `hoody cron delete` | `rm`, `remove` |
| `hoody cron update` | `edit` |