> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/block/goose/llms.txt
> Use this file to discover all available pages before exploring further.

# Schedule Command

> Manage scheduled Goose jobs and automated recipe execution

The `schedule` command manages scheduled jobs that run Goose recipes automatically at specified times.

## Usage

```bash theme={null}
goose schedule <subcommand> [OPTIONS]
goose sched <subcommand> [OPTIONS]  # short alias
```

## Subcommands

### Add Scheduled Job

Add a new scheduled job.

```bash theme={null}
goose schedule add --schedule-id <ID> --cron <EXPRESSION> --recipe-source <PATH>
```

**Options:**

<ParamField path="--schedule-id" type="string" required>
  Unique ID for the recurring scheduled job.

  **Alias:** `--id`

  **Example:** `--schedule-id daily-report`
</ParamField>

<ParamField path="--cron" type="string" required>
  Cron expression for when to run the job.

  **Examples:**

  * `0 * * * *` - Every hour at minute 0
  * `0 9 * * *` - Every day at 9:00 AM
  * `0 0 * * 1` - Every Monday at midnight
  * `@hourly` - Every hour
  * `@daily` - Every day at midnight
</ParamField>

<ParamField path="--recipe-source" type="string" required>
  Path to recipe file or base64 encoded recipe string.

  **Example:** `--recipe-source ./recipes/daily-report.yaml`
</ParamField>

**Examples:**

```bash theme={null}
# Hourly report
goose schedule add \
  --schedule-id hourly-report \
  --cron "0 * * * *" \
  --recipe-source ./report.yaml

# Daily backup at 2 AM
goose schedule add \
  --schedule-id daily-backup \
  --cron "0 2 * * *" \
  --recipe-source backup.yaml

# Weekly summary every Monday at 9 AM
goose schedule add \
  --schedule-id weekly-summary \
  --cron "0 9 * * 1" \
  --recipe-source summary.yaml
```

**Output:**

```bash theme={null}
✅ Using standard 5-field cron format: 0 * * * *
Scheduled job 'hourly-report' added. Recipe expected at ~/.config/goose/scheduled_recipes/hourly-report.yaml
```

### List Scheduled Jobs

List all scheduled jobs.

```bash theme={null}
goose schedule list
```

**Example output:**

```bash theme={null}
Scheduled Jobs:
- ID: daily-report
  Status: ⏹️  IDLE
  Cron: 0 9 * * *
  Recipe Source (in store): daily-report.yaml
  Last Run: 2025-03-04T09:00:00+00:00

- ID: hourly-backup  
  Status: 🟢 RUNNING
  Cron: 0 * * * *
  Recipe Source (in store): hourly-backup.yaml
  Last Run: 2025-03-04T14:00:00+00:00

- ID: weekly-summary
  Status: ⏸️  PAUSED
  Cron: 0 9 * * 1
  Recipe Source (in store): weekly-summary.yaml
  Last Run: Never
```

**Status indicators:**

* 🟢 `RUNNING` - Currently executing
* ⏹️ `IDLE` - Waiting for next scheduled time
* ⏸️ `PAUSED` - Temporarily disabled

### Remove Scheduled Job

Remove a scheduled job by ID.

```bash theme={null}
goose schedule remove --schedule-id <ID>
```

**Options:**

<ParamField path="--schedule-id" type="string" required>
  ID of the scheduled job to remove.

  **Alias:** `--id`
</ParamField>

**Example:**

```bash theme={null}
goose schedule remove --schedule-id daily-report
```

**Output:**

```bash theme={null}
Scheduled job 'daily-report' and its associated recipe removed.
```

### List Schedule Sessions

List sessions created by a specific schedule.

```bash theme={null}
goose schedule sessions --schedule-id <ID> [--limit <N>]
```

**Options:**

<ParamField path="--schedule-id" type="string" required>
  ID of the schedule.

  **Alias:** `--id`
</ParamField>

<ParamField path="--limit" type="number" default="50">
  Maximum number of sessions to return.

  **Short:** `-l`
</ParamField>

**Example:**

```bash theme={null}
goose schedule sessions --schedule-id daily-report --limit 10
```

**Output:**

```bash theme={null}
Sessions for schedule ID 'daily-report':
  - Session ID: 20250304_090000, Working Dir: /home/user, Description: "Daily Report", Schedule ID: daily-report
  - Session ID: 20250303_090000, Working Dir: /home/user, Description: "Daily Report", Schedule ID: daily-report
```

### Run Schedule Now

Trigger a scheduled job immediately.

```bash theme={null}
goose schedule run-now --schedule-id <ID>
```

**Options:**

<ParamField path="--schedule-id" type="string" required>
  ID of the schedule to run.

  **Alias:** `--id`
</ParamField>

**Example:**

```bash theme={null}
goose schedule run-now --schedule-id daily-report
```

**Output:**

```bash theme={null}
Successfully triggered schedule 'daily-report'. New session ID: 20250304_143022
```

### Cron Expression Help

Show cron expression examples and help.

```bash theme={null}
goose schedule cron-help
```

**Output:**

```bash theme={null}
📅 Cron Expression Guide for goose Scheduler
===========================================

🕐 HOURLY SCHEDULES (Most Common Request):
  0 * * * *       - Every hour at minute 0 (e.g., 1:00, 2:00, 3:00...)
  30 * * * *      - Every hour at minute 30 (e.g., 1:30, 2:30, 3:30...)
  0 */2 * * *     - Every 2 hours at minute 0 (e.g., 2:00, 4:00, 6:00...)
  @hourly         - Every hour (same as "0 * * * *")

📅 DAILY SCHEDULES:
  0 9 * * *       - Every day at 9:00 AM
  0 0 * * *       - Every day at midnight
  @daily          - Every day at midnight

📆 WEEKLY SCHEDULES:
  0 9 * * 1       - Every Monday at 9:00 AM
  0 17 * * 5      - Every Friday at 5:00 PM
  @weekly         - Every Sunday at midnight

🗓️  MONTHLY SCHEDULES:
  0 9 1 * *       - First day of every month at 9:00 AM
  @monthly        - First day of every month at midnight

📝 CRON FORMAT:
  ┌─── minute (0 - 59)
  │ ┌─── hour (0 - 23)
  │ │ ┌─── day of month (1 - 31)
  │ │ │ ┌─── month (1 - 12)
  │ │ │ │ ┌─── day of week (0 - 7, Sunday = 0 or 7)
  │ │ │ │ │
  * * * * *
```

### Services Status (Deprecated)

Check status of scheduler services.

```bash theme={null}
goose schedule services-status
```

**Output:**

```bash theme={null}
Service management has been removed as Temporal scheduler is no longer supported.
The built-in scheduler runs within the goose process and requires no external services.
```

### Services Stop (Deprecated)

Stop scheduler services.

```bash theme={null}
goose schedule services-stop
```

**Output:**

```bash theme={null}
Service management has been removed as Temporal scheduler is no longer supported.
The built-in scheduler runs within the goose process and requires no external services.
```

## Cron Expressions

### Format

**Standard 5-field:**

```
minute hour day month weekday
```

**Extended 6-field (with seconds):**

```
second minute hour day month weekday
```

### Special Characters

<ParamField path="*" type="char">
  Any value - matches all (e.g., `*` in hour = every hour)
</ParamField>

<ParamField path="*/n" type="pattern">
  Every nth interval (e.g., `*/5` in minute = every 5 minutes)
</ParamField>

<ParamField path="n-m" type="range">
  Range of values (e.g., `1-5` = 1,2,3,4,5)
</ParamField>

<ParamField path="n,m" type="list">
  List of values (e.g., `1,3,5` = 1 or 3 or 5)
</ParamField>

### Shorthand Expressions

<ParamField path="@yearly" type="shorthand">
  Once a year - equivalent to `0 0 1 1 *`

  **Alias:** `@annually`
</ParamField>

<ParamField path="@monthly" type="shorthand">
  Once a month - equivalent to `0 0 1 * *`
</ParamField>

<ParamField path="@weekly" type="shorthand">
  Once a week - equivalent to `0 0 * * 0`
</ParamField>

<ParamField path="@daily" type="shorthand">
  Once a day - equivalent to `0 0 * * *`

  **Alias:** `@midnight`
</ParamField>

<ParamField path="@hourly" type="shorthand">
  Once an hour - equivalent to `0 * * * *`
</ParamField>

### Common Examples

**Every 15 minutes:**

```bash theme={null}
--cron "*/15 * * * *"
```

**Every hour at 30 minutes:**

```bash theme={null}
--cron "30 * * * *"
```

**Every 2 hours:**

```bash theme={null}
--cron "0 */2 * * *"
```

**Business hours (9 AM - 5 PM, weekdays):**

```bash theme={null}
--cron "0 9-17 * * 1-5"
```

**First day of month:**

```bash theme={null}
--cron "0 0 1 * *"
```

**Weekends only:**

```bash theme={null}
--cron "0 10 * * 0,6"
```

## Recipe Storage

Scheduled recipes are stored in `~/.config/goose/scheduled_recipes/`:

```
~/.config/goose/scheduled_recipes/
├── daily-report.yaml
├── hourly-backup.yaml
└── weekly-summary.yaml
```

When you add a schedule, the recipe is copied to this directory.

## Session Tracking

Each scheduled execution creates a session:

**Session metadata includes:**

* `schedule_id` - Links to the schedule
* `working_dir` - Execution directory
* `name` - Session description
* Creation timestamp

**View scheduled sessions:**

```bash theme={null}
goose schedule sessions --schedule-id daily-report
goose session list  # All sessions (includes scheduled)
```

## Error Handling

**Invalid cron expression:**

```bash theme={null}
⚠️  Unusual cron format detected: '* * *'
   Common formats:
   - 5 fields: '0 * * * *'
```

**Job already exists:**

```bash theme={null}
Error: Job with ID 'daily-report' already exists.
```

**Job not found:**

```bash theme={null}
Error: Job with ID 'unknown-job' not found.
```

**Recipe validation error:**

```bash theme={null}
Error with recipe source: Recipe validation failed. Path: ./invalid.yaml
```

## Examples

**Hourly data sync:**

```bash theme={null}
goose schedule add \
  --schedule-id hourly-sync \
  --cron "0 * * * *" \
  --recipe-source ./recipes/sync-data.yaml
```

**Daily report at 9 AM:**

```bash theme={null}
goose schedule add \
  --schedule-id daily-report \
  --cron "0 9 * * *" \
  --recipe-source ./recipes/generate-report.yaml
```

**Weekly cleanup on Sundays:**

```bash theme={null}
goose schedule add \
  --schedule-id weekly-cleanup \
  --cron "0 0 * * 0" \
  --recipe-source ./recipes/cleanup.yaml
```

**Test schedule immediately:**

```bash theme={null}
# Add schedule
goose schedule add --schedule-id test-job --cron "@hourly" --recipe-source test.yaml

# Run now to test
goose schedule run-now --schedule-id test-job

# Check sessions
goose schedule sessions --schedule-id test-job
```

**Remove old schedule:**

```bash theme={null}
goose schedule remove --schedule-id old-job
```

## Built-in Scheduler

Goose includes a built-in scheduler:

* **No external services** required
* Runs within Goose process
* Persistent across restarts
* Automatic session creation
* Error logging and recovery

**Storage:**

* Schedules: `~/.config/goose/scheduler.json`
* Recipes: `~/.config/goose/scheduled_recipes/`
* Sessions: `~/.config/goose/sessions/`

## See Also

* [Recipe Command](/api/cli/recipe) - Working with recipes
* [Session Command](/api/cli/session) - Managing sessions
* Scheduling guide (link to guide)