<!--
hoody-cron Subskill (cli)
Auto-generated by Hoody Skills Generator
Generated: 2026-06-19T23:01:43.880Z
Model: mimo-v2.5-pro
Mode: cli


Tokens: 6477

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

# hoody-cron Subskill

Managed cron job scheduling with enable/disable controls and auto-expiration for Hoody containers.

---

## Overview

### What It Does

hoody-cron provides managed cron job scheduling for containerized workloads. It enables:

- **Scheduled task execution** using standard cron syntax
- **Per-user crontab management** with isolated namespaces
- **Entry-level operations** for individual scheduled jobs
- **Auto-expiration** of stale or inactive cron entries
- **Enable/disable controls** without deleting configuration

### When to Use

| Scenario | Use hoody-cron When |
|----------|---------------------|
| Periodic cleanup | Container needs scheduled maintenance tasks |
| Data sync | External API polling or batch imports |
| Report generation | Automated report creation at specific intervals |
| Health checks | Custom monitoring beyond built-in health endpoints |
| Backup automation | Scheduled database or file backups |

### How It Fits Hoody Philosophy

hoody-cron follows core Hoody principles:

1. **Container-scoped** — All cron operations target specific containers via `-c <container-id>`
2. **CLI-first** — All operations use `hoody cron` commands, never direct HTTP
3. **Managed lifecycle** — Auto-expiration prevents resource leaks from forgotten jobs
4. **User isolation** — Each user's crontab is independent and isolated

### Architecture

```
┌─────────────────────────────────────────────────┐
│                  hoody CLI                       │
│              hoody cron <cmd>                    │
└─────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────┐
│              hoody-cron Service                  │
│  ┌───────────┐  ┌───────────┐  ┌─────────────┐ │
│  │ Crontabs  │  │  Entries  │  │   Scheduler │ │
│  └───────────┘  └───────────┘  └─────────────┘ │
└─────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────┐
│           Container Runtime                      │
│       Executes scheduled commands                │
└─────────────────────────────────────────────────┘
```

---

## Common Workflows

### Workflow 1: Basic Health Check and Service Discovery

Verify the cron service is operational before scheduling jobs.

```
# Step 1: Check cron service health
hoody cron health

# Step 2: List all existing crontabs (system-wide)
hoody cron list
```

**Expected health response:**

```
{
  "status": "ok",
  "service": "hoody-cron"
}
```

**When to proceed:** Health returns `"status": "ok"` and no connection errors occur.

---

### Workflow 2: View a User's Crontab

Retrieve the complete crontab configuration for a specific user.

```
# Get full crontab for user "alice"
hoody cron get alice

# Get crontab with machine-readable output
hoody cron get alice -o json
```

**Expected response:**

```
{
  "user": "alice",
  "crontab": "0 2 * * * /app/backup.sh",
  "entries": []
}
```

**Interpretation:**
- `crontab` contains the raw cron expression (if using raw mode)
- `entries` contains structured individual jobs (if using entry mode)

---

### Workflow 3: Create a Scheduled Job

Add a new cron entry to a user's crontab.

```
# Create a daily backup job at 2:00 AM
hoody cron create alice \
  --command "/app/backup.sh --full" \
  --schedule "0 2 * * *"

# Create a job with machine-readable output
hoody cron create alice \
  --command "/app/cleanup.sh" \
  --schedule "*/30 * * * *" \
  -o json
```

**Expected response:**

```
{
  "id": "507f1f77bcf86cd799439011",
  "user": "alice",
  "command": "/app/backup.sh --full",
  "schedule": "0 2 * * *",
  "enabled": true
}
```

**State verification:** Save the returned `id` — required for update/delete operations.

---

### Workflow 4: List and Inspect Entries

View all scheduled entries for a user, then inspect a specific one.

```
# Step 1: List all entries for user "alice"
hoody cron list alice

# Step 2: Get details for a specific entry (using id from list)
hoody cron get alice 507f1f77bcf86cd799439011

# Step 3: Get entry with JSON output for scripting
hoody cron get alice 507f1f77bcf86cd799439011 -o json
```

**Expected list response:**

```
{
  "user": "alice",
  "entries": [
    {
      "id": "507f1f77bcf86cd799439011",
      "command": "/app/backup.sh --full",
      "schedule": "0 2 * * *",
      "enabled": true
    },
    {
      "id": "507f1f77bcf86cd799439012",
      "command": "/app/cleanup.sh",
      "schedule": "*/30 * * * *",
      "enabled": true
    }
  ]
}
```

**Expected single entry response:**

```
{
  "id": "507f1f77bcf86cd799439011",
  "user": "alice",
  "command": "/app/backup.sh --full",
  "schedule": "0 2 * * *",
  "enabled": true,
  "lastRun": null,
  "nextRun": "2025-11-06T02:00:00Z"
}
```

---

### Workflow 5: Modify an Existing Job

Update the schedule or command of an existing cron entry.

```
# Update the schedule to run at 3:00 AM instead of 2:00 AM
hoody cron update alice 507f1f77bcf86cd799439011 \
  --schedule "0 3 * * *"

# Update the command
hoody cron update alice 507f1f77bcf86cd799439011 \
  --command "/app/backup.sh --incremental"

# Update both schedule and command
hoody cron update alice 507f1f77bcf86cd799439011 \
  --schedule "0 4 * * 0" \
  --command "/app/backup.sh --weekly"
```

**Verification step:** Always confirm the update took effect.

```
# Verify the update
hoody cron get alice 507f1f77bcf86cd799439011 -o json
```

**Expected response after update:**

```
{
  "id": "507f1f77bcf86cd799439011",
  "user": "alice",
  "command": "/app/backup.sh --weekly",
  "schedule": "0 4 * * 0",
  "enabled": true
}
```

---

### Workflow 6: Delete a Scheduled Job

Remove a cron entry that is no longer needed.

```
# Delete requires confirmation (--yes skips the prompt)
hoody cron delete alice 507f1f77bcf86cd799439011 --yes

# Interactive confirmation (will prompt)
hoody cron delete alice 507f1f77bcf86cd799439011
```

**Verification step:** Confirm the entry was removed.

```
# List entries to confirm deletion
hoody cron list alice -o json
```

**Expected response after deletion:**

```
{
  "user": "alice",
  "entries": [
    {
      "id": "507f1f77bcf86cd799439012",
      "command": "/app/cleanup.sh",
      "schedule": "*/30 * * * *",
      "enabled": true
    }
  ]
}
```

---

### Workflow 7: Replace Entire Crontab

Overwrite a user's complete crontab configuration.

```
# Replace with a new crontab (reads from stdin or file)
hoody cron replace alice --crontab "0 2 * * * /app/backup.sh
*/30 * * * * /app/cleanup.sh"

# Replace using a file
cat /path/to/new-crontab.txt | hoody cron replace alice --crontab -
```

**Expected response:**

```
{
  "user": "alice",
  "crontab": "0 2 * * * /app/backup.sh\n*/30 * * * * /app/cleanup.sh",
  "entries": []
}
```

**Warning:** This replaces the entire crontab. Any entries not included will be removed.

---

## Advanced Operations

### Multi-Step Workflow: Container-Scoped Cron Management

When targeting a specific container, include the `-c` flag.

```
# Step 1: Identify target container
CONTAINER_ID="abc123def456"

# Step 2: Check service health for that container
hoody cron health -c $CONTAINER_ID

# Step 3: Create entry targeting container
hoody cron create alice \
  --command "/app/refresh-cache.sh" \
  --schedule "*/15 * * * *" \
  -c $CONTAINER_ID \
  -o json

# Step 4: Verify entry was created
hoody cron list alice -c $CONTAINER_ID -o json
```

**Expected health response for container:**

```
{
  "status": "ok",
  "service": "hoody-cron",
  "container": "abc123def456"
}
```

---

### Batch Operations: Managing Multiple Jobs

Create and verify multiple cron entries in sequence.

```
# Define user and container
USER="devteam"
CONTAINER="proj-abc-frontend-svc-123"

# Create multiple entries
hoody cron create $USER \
  --command "/app/sync-data.sh" \
  --schedule "0 */6 * * *" \
  -c $CONTAINER

hoody cron create $USER \
  --command "/app/generate-report.sh" \
  --schedule "0 8 * * 1-5" \
  -c $CONTAINER

hoody cron create $USER \
  --command "/app/cleanup-temp.sh" \
  --schedule "0 0 * * *" \
  -c $CONTAINER

# Verify all entries
hoody cron list $USER -c $CONTAINER -o json
```

**Expected list response:**

```
{
  "user": "devteam",
  "entries": [
    {
      "id": "609e1f88bcf86cd799439021",
      "command": "/app/sync-data.sh",
      "schedule": "0 */6 * * *",
      "enabled": true
    },
    {
      "id": "609e1f88bcf86cd799439022",
      "command": "/app/generate-report.sh",
      "schedule": "0 8 * * 1-5",
      "enabled": true
    },
    {
      "id": "609e1f88bcf86cd799439023",
      "command": "/app/cleanup-temp.sh",
      "schedule": "0 0 * * *",
      "enabled": true
    }
  ]
}
```

---

### Error Recovery: Handling Failed Operations

**Scenario 1: Invalid cron schedule**

```
# This will fail with an error
hoody cron create alice --command "/app/test.sh" --schedule "invalid"
```

**Expected error:**

```
{
  "error": "Invalid cron expression",
  "message": "Schedule 'invalid' is not a valid cron expression"
}
```

**Recovery:** Correct the schedule syntax and retry.

```
# Retry with valid syntax
hoody cron create alice \
  --command "/app/test.sh" \
  --schedule "*/5 * * * *"
```

---

**Scenario 2: Entry not found**

```
# Attempting to get a non-existent entry
hoody cron get alice nonexistent-id
```

**Expected error:**

```
{
  "error": "Not found",
  "message": "Entry 'nonexistent-id' not found for user 'alice'"
}
```

**Recovery:** List entries to find the correct ID.

```
# Get correct entry ID
hoody cron list alice -o json
```

---

**Scenario 3: User not found**

```
# Attempting operations on non-existent user
hoody cron list nonexistentuser
```

**Expected response:**

```
{
  "user": "nonexistentuser",
  "entries": []
}
```

**Note:** The service returns an empty list rather than an error for unknown users. Create an entry first if the user needs to exist.

---

### Performance Considerations

| Operation | Recommended Pattern |
|-----------|---------------------|
| Bulk reads | Use `hoody cron list <user>` instead of multiple `get` calls |
| Machine output | Always use `-o json` when scripting or piping |
| Container targeting | Set `HOODY_CONTAINER` env var instead of `-c` flag for long sessions |
| Confirmation skip | Use `--yes` for delete operations in automated scripts |

**Environment variable for container targeting:**

```
# Set container once for the session
export HOODY_CONTAINER="proj-abc-frontend-svc-123"

# Now commands don't need -c flag
hoody cron list alice
hoody cron create alice --command "/app/task.sh" --schedule "0 * * * *"
hoody cron delete alice some-entry-id --yes
```

---

## Quick Reference

### Essential Commands

| Command | Description |
|---------|-------------|
| `hoody cron health` | Service health check |
| `hoody cron list` | List all crontabs |
| `hoody cron list <user>` | List entries for user |
| `hoody cron create <user>` | Create entry (requires `--command`, `--schedule`) |
| `hoody cron get <user>` | Get full crontab |
| `hoody cron get <user> <id>` | Get single entry |
| `hoody cron update <user> <id>` | Update entry |
| `hoody cron delete <user> <id>` | Delete entry (use `--yes` to skip confirmation) |
| `hoody cron replace <user>` | Replace entire crontab |

### Key Parameters

| Parameter | Usage |
|-----------|-------|
| `<user>` | Target user namespace (positional arg) |
| `<id>` | Entry identifier (positional arg) |
| `--command` | Shell command to execute (required for create) |
| `--schedule` | Cron expression: `min hour day month weekday` (required for create) |
| `--crontab` | Raw crontab content (required for replace) |
| `-c <container-id>` | Target container (or set `HOODY_CONTAINER` env) |
| `-o json` | Output as JSON |
| `--yes` | Skip delete confirmation |

### Cron Expression Reference

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

**Common patterns:**

| Expression | Meaning |
|------------|---------|
| `*/5 * * * *` | Every 5 minutes |
| `0 * * * *` | Every hour at minute 0 |
| `0 2 * * *` | Daily at 2:00 AM |
| `0 0 * * 0` | Weekly on Sunday at midnight |
| `0 8 * * 1-5` | Weekdays at 8:00 AM |

### CLI Authentication

```
# Option 1: Interactive login
hoody auth login

# Option 2: Token flag
hoody cron list alice --token <your-token>

# Option 3: Environment variable
export HOODY_TOKEN=<your-token>
hoody cron list alice
```