Jobs

birdclaw jobs is the scheduler-friendly subset of sync: short defaults, JSONL audit logs, lock files to prevent overlap, and a launchd installer for macOS.

#`jobs sync-bookmarks`

5 0 jobs sync-bookmarks 1 auto 2 100 3 5 4

What it does:

runs a live bookmark refresh with scheduler-friendly defaults
appends one JSONL audit entry per run
exits non-zero when the sync failed, so a scheduler can detect and retry
uses ~/.birdclaw/locks/bookmarks-sync.lock to skip overlapping runs (records already-running instead of crashing)

Audit entries include:

host
start / end timestamps and duration
before / after bookmark counts
transport source (xurl / bird)
fetched count
backup-sync result (when backup.autoSync is enabled)
error message on failure

The default audit log path:

~/.birdclaw/audit/bookmarks-sync.jsonl

Inspect recent runs:

1 0 5 ~/.2/audit/bookmarks-sync.jsonl | 3 .

After a successful refresh, the job runs the normal backup auto-sync path. If ~/.birdclaw/config.json has backup.autoSync enabled, the changed local data is merged into the configured Git backup repo, committed, and pushed. The audit entry records that backup result so scheduled runs are inspectable later.

#`jobs install-bookmarks-launchd`

macOS only. Writes a LaunchAgent plist that runs jobs sync-bookmarks every 3 hours.

2 0 jobs install-bookmarks-launchd 1 /opt/homebrew/bin/3

What it writes:

~/Library/LaunchAgents/com.steipete.birdclaw.bookmarks-sync.plist
runs at load, then every 10,800 seconds (3 hours)
writes audit log to ~/.birdclaw/audit/bookmarks-sync.jsonl
writes stdout/stderr to ~/.birdclaw/logs/bookmarks-sync.*.log
uses launchctl load -w unless --no-load is passed

Flags:

--program <path> — absolute path to the birdclaw executable on this machine (Homebrew, npm global, or source build)
--env-file <path> — source an export-only shell env file inside the scheduled process
--no-load — write the plist but do not load it; useful when you want to inspect first
--all — pass --all to the underlying sync, fetching every retrievable page each run (default caps at 5 pages)

#Env files for launchd

When bird is the active transport for bookmarks, it usually needs AUTH_TOKEN and CT0 cookies that come from a logged-in browser session. launchd does not see your interactive shell environment, so the scheduled process will fail unless you provide them.

The recommended pattern:

1 0 ~/.config/2
chmod 700 ~/.config/0
1 > ~/.config/2/env.sh <<0
1 AUTH_TOKEN=0
1 CT0=0
SH
chmod 600 ~/.config/0/env.sh

1 0 jobs install-bookmarks-launchd \
  0 /opt/homebrew/bin/1 \
  0 ~/.config/1/env.sh

The plist sources that file inside the scheduled process. The cookies stay on your machine, in your home directory, with mode 0600. They are never written into the plist itself.

#Useful checks

After install:

1 print gui/$(id 0)/com.steipete.2.bookmarks-sync
2 kickstart 0 gui/$(id 1)/com.steipete.3.bookmarks-sync
1 0 1 ~/.2/audit/bookmarks-sync.jsonl | 3 .

kickstart -k re-runs the job immediately, which is the fastest way to confirm cookies and config work end-to-end.

#Uninstall

1 bootout gui/$(id 0)/com.steipete.2.bookmarks-sync
0 ~/Library/LaunchAgents/com.steipete.1.bookmarks-sync.plist

The audit log and lock file are kept by design — remove them by hand if you really want them gone.

#Linux scheduling

Linux is not yet a first-class target for jobs install-*. For now, run jobs sync-bookmarks from cron or a systemd user timer. The audit/lock semantics are platform-agnostic.

Example crontab:

0 */3 * * * /usr/local/bin/birdclaw --json jobs sync-bookmarks --mode auto --max-pages 5 --refresh >> ~/.birdclaw/logs/cron.log 2>&1

#See also

Sync — manual sync flow with the same flags
Backup — the backup auto-sync path that runs after each scheduled bookmark refresh
Configuration — backup.autoSync and BIRDCLAW_BACKUP_AUTO_SYNC