Schedule Reference

Scheduled sync jobs

Register config-based sync runs with the host operating system scheduler. Godwit Sync installs one-shot jobs and does not run a scheduler daemon.

Install a job

schedule install validates the sync config and registers the current Godwit Sync executable with a recurring trigger.

godwit schedule install --name nightly --config ./nightly.yaml --daily-at 02:00

godwit schedule install --name hourly --config ./hourly.yaml --every 1h

godwit schedule install --name weekdays --config ./weekdays.yaml --cron "0 6 * * 1-5"

Flag	Type	Default	Behavior
`--name`	string	required	Unique job name.
`--config`	string	required	Sync YAML file. Installation fails if the file is missing or invalid.
`--cron`	string	none	Canonical five-field cron expression: minute, hour, day of month, month, day of week.
`--every`	duration	none	Positive Go duration such as 30m or 1h.
`--daily-at`	HH:MM	none	Daily local time in 24-hour HH:MM form.
`--backend`	string	auto	auto, systemd, cron, launchd, or taskscheduler.
`--system`	bool	false	Install in the host-wide scheduler scope. Requires root or Administrator.
`--extra-arg`	stringArray	none	Append one sync argument after sync --config. Repeat for multiple arguments.

Set exactly one of --cron, --every, or --daily-at. Job names must match [A-Za-z0-9._-]+. Godwit Sync stores absolute paths for the config and executable.

List, inspect, and remove jobs

Management commands use the selected backend. When install forced a backend instead of auto, pass the same --backend value to status and remove.

godwit schedule list
godwit schedule status --name nightly
godwit schedule remove --name nightly

Command	Behavior
`godwit schedule list`	List registered job names, backends, schedules, config paths, and available next-run times.
`godwit schedule status --name <NAME>`	Report whether the job is installed and active. Next-run data is backend-dependent.
`godwit schedule remove --name <NAME>`	Remove the OS scheduler artifact and Godwit Sync registry entry.
`godwit schedule remove --name <NAME> --if-exists`	Return exit code 0 when the job is absent.

Scheduler backends

--backend auto selects a scheduler from the current operating system.

Host	Backend	Behavior
Linux	`systemd`	Selected when systemd is running and systemctl is available. Otherwise auto selects cron.
Linux / Unix	`cron`	Uses the user crontab or /etc/cron.d with --system. Cron and launchd output is written under ~/.godwit/logs.
macOS	`launchd`	Uses a LaunchAgent or a LaunchDaemon with --system.
Windows	`taskscheduler`	Uses schtasks. --system configures the task to run as SYSTEM.

--system creates a host-wide systemd unit, cron.d entry, launchd daemon, or Task Scheduler task under SYSTEM.

Backend adapters reject schedules they cannot represent. systemd rejects simultaneous day-of-month and day-of-week restrictions. cron intervals must map to cron fields. launchd rejects expansions above 500 calendar entries. Task Scheduler accepts common daily, weekly, monthly, and interval forms.

Keyring credentials

Store static S3 credentials by name, then reference that name from a scheduled sync config.

godwit secret set prod-backup
godwit secret list
godwit secret get prod-backup
godwit secret rm prod-backup

Command	Behavior
`godwit secret set <NAME>`	Store access key, secret key, and optional session token. Missing key flags trigger no-echo terminal prompts.
`godwit secret list`	Print stored names only.
`godwit secret get <NAME>`	Confirm that the named credential exists without printing values.
`godwit secret get <NAME> --show`	Print credential values. The command refuses non-terminal output.
`godwit secret rm <NAME>`	Delete the named credential.

Config reference

source:
  url: s3://production/data
  endpoint: s3.amazonaws.com
  auth_mode: keyring
  secret_ref: prod-backup
destination:
  url: ./backup

Godwit Sync uses the native OS keychain when available and an encrypted file under ~/.godwit/secrets as fallback. Set GODWIT_KEYRING_PASSWORD for non-interactive access to the file backend. GODWIT_HOME overrides the ~/.godwit application directory.