Scheduled Execution

Nefia includes a built-in cron scheduler that automates recurring tasks -- backups, log rotation, health checks, compliance scans -- across your fleet. Schedules are defined and managed through the CLI and executed by the Nefia daemon process. Schedule state syncs with the web dashboard so your team has visibility into upcoming and past runs.

Creating a Schedule

Use nefia schedule create to define a recurring playbook run:

nefia schedule create \
  --name daily-backup \
  --cron "0 2 * * *" \
  --playbook backup \
  --target all

Four flags are required: --name, --cron, --playbook, and --target. The --target flag accepts the same host selectors used elsewhere (all, host:<name>, group:<name>, tag:<name>, etc.).

After creation, the CLI prints the schedule ID and the next 3 upcoming run times:

Optional Flags

Example with all optional flags:

nefia schedule create \
  --name web-health \
  --cron "*/5 * * * *" \
  --playbook health-check \
  --target group:webservers \
  --timezone "America/New_York" \
  --var retention_days=30 \
  --var alert_threshold=5 \
  --overlap-policy skip \
  --missed-run-policy run_once \
  --description "Check web server health every 5 minutes"

Managing Schedules

List All Schedules

nefia schedule list

The list command also shows whether the daemon is currently running:

If the daemon is not running, the output warns you:

Show Schedule Details

nefia schedule show daily-backup

Displays the full schedule definition, including cron description, variables, policies, last run status, and the next 5 upcoming runs:

You can reference schedules by name or ID in all subcommands.

Update a Schedule

nefia schedule update daily-backup --cron "30 1 * * *"
nefia schedule update daily-backup --playbook backup-v2 --target group:production
nefia schedule update daily-backup --timezone "Asia/Tokyo" --description "Updated backup"
nefia schedule update daily-backup --overlap-policy skip --missed-run-policy run_once

Only the flags you pass are changed; everything else is preserved. The following flags are available:

Enable and Disable

nefia schedule disable daily-backup   # Temporarily pause
nefia schedule enable daily-backup    # Resume

Disabled schedules are skipped by the daemon but remain in the schedule list.

Delete a Schedule

nefia schedule delete daily-backup

Prompts for confirmation unless --yes is passed. Deletion is permanent and removes the schedule definition and its state.

Execution History

View past runs for a specific schedule:

nefia schedule history daily-backup

View history across all schedules:

nefia schedule history

Limit the number of records:

nefia schedule history daily-backup --limit 5

The default limit is 20 records.

Manual Trigger

Trigger a schedule immediately without waiting for the next cron window:

nefia schedule trigger daily-backup

This runs the playbook with the same target and variables as the schedule definition. The schedule does not need to be enabled. Manual triggers execute the playbook directly and do not require the daemon to be running.

The run is recorded in the history with trigger: manual.

Overlap and Missed-Run Policies

Overlap Policy

Controls what happens when a new cron window fires while the previous execution is still running.

Missed-Run Policy

Controls what happens when the daemon comes back online after missing one or more scheduled windows.

Set policies at creation time:

nefia schedule create \
  --name critical-backup \
  --cron "0 */6 * * *" \
  --playbook backup \
  --target all \
  --overlap-policy cancel_running \
  --missed-run-policy run_once

Or update them later:

nefia schedule update critical-backup --overlap-policy skip --missed-run-policy skip

Running the Daemon

Schedules require the Nefia daemon to be running. In addition to the cron scheduler, the daemon manages several background subsystems:

Start in Foreground

nefia daemon

Or equivalently:

nefia daemon run

The daemon runs until interrupted (Ctrl+C / SIGTERM). It acquires an exclusive PID lock to prevent multiple instances.

Install as a System Service

For persistent operation, generate a platform-specific service configuration with nefia daemon install. The output is printed to stdout so you can redirect it to the appropriate location.

nefia daemon install > ~/Library/LaunchAgents/ai.nefia.daemon.plist
launchctl load ~/Library/LaunchAgents/ai.nefia.daemon.plist

Graceful Shutdown

When the daemon receives a shutdown signal, it:

1. Stops accepting new schedule executions
2. Cancels all running executions
3. Waits up to 60 seconds for in-flight executions to complete
4. Persists final schedule state to disk

Crash Recovery

If the daemon crashes while an execution is in progress, it records the crashed execution as cancelled with the message "daemon crashed during execution" on the next startup. This ensures the execution history remains accurate.

Web Dashboard Sync

When authenticated (via nefia login), the daemon periodically syncs schedule definitions and execution history to the web dashboard. This gives your team visibility into schedules without needing CLI access.

The sync interval is controlled by the sync_interval_sec configuration option (default: 300 seconds / 5 minutes). The sync endpoint is POST /api/schedules/sync and uses the same authentication as other API calls.

The sync is one-directional: CLI to dashboard. Schedules are always created and managed through the CLI.

Configuration

Schedule settings in nefia.yaml:

schedule:
  enabled: true
  sync_interval_sec: 300
  retention_days: 90
  max_concurrent_schedules: 5

JSON Output

All schedule commands support --output json for scripting and automation:

nefia schedule list --output json
nefia schedule show daily-backup --output json
nefia schedule history daily-backup --output json

Quick Reference

MCP Tools

All schedule operations are available via MCP for AI agent orchestration:

Related