Container Run Once Mode

Run a local sync that waits for completion and returns an exit code.

cw sync once runs a sync in the current process. It waits for completion, then exits with a result code.

Use it for external automation, including cron, one-shot Docker containers, Kubernetes CronJobs, and CI checks.

cw sync run sends work to the running CrossWatch service. cw sync once does not. It runs the sync locally.

Use cw sync once when your scheduler needs the command's exit code. Use cw sync run when CrossWatch is already running and should manage the work.

Start a sync

Run all enabled sync pairs:

cw sync once

Run one pair by its number, ID, unique ID prefix, or label:

cw sync once 1

cw sync once pair_07c3

Run several pairs:

cw sync once --pair pair_07c3 --pair pair_91ab

Run only specific features:

cw sync once --feature watchlist

cw sync once --feature watchlist --feature ratings

Available feature names:

watchlist
ratings
history
progress
playlists
collection

Preview changes

Add --dry-run to inspect the sync without changing any provider data:

cw sync once --dry-run

Use in automation

Add --json to print the final summary as JSON. This works well with scripts and monitoring tools.

cw sync once --json

Combine it with pair selection when needed:

cw sync once --pair pair_07c3 --json

Exit status

The command returns one of these codes:

0  Sync completed without errors.
1  Sync failed, was cancelled, or met a strict failure condition.

Unresolved and skipped items do not fail the command by default. Enable strict checks when automation must treat them as failures.

Fail when CrossWatch cannot resolve an item:

cw sync once --fail-on-unresolved

Fail when CrossWatch skips an item:

cw sync once --fail-on-skipped

Combine both checks:

cw sync once --fail-on-unresolved --fail-on-skipped

Preserve the last-sync marker

The command updates the last-sync state marker when configured. This marker helps CrossWatch track completed syncs.

Add --no-state-json to leave the marker unchanged:

cw sync once --no-state-json

Run a one-shot Docker container

Mount the same configuration volume used by CrossWatch. The container runs one sync, then --rm removes it.

docker run --rm \
  -v crosswatch_config:/config \
  -e TZ=Europe/Amsterdam \
  ghcr.io/cenodude/crosswatch:latest \
  cw sync once

Select specific pairs:

docker run --rm \
  -v crosswatch_config:/config \
  ghcr.io/cenodude/crosswatch:latest \
  cw sync once --pair pair_07c3 --pair pair_91ab

Use strict mode with JSON output for cron or Kubernetes:

docker run --rm \
  -v crosswatch_config:/config \
  ghcr.io/cenodude/crosswatch:latest \
  cw sync once --fail-on-unresolved --json

Choose the right command

Use cw sync once when an external scheduler needs the completed sync result.

Use cw sync run when the running CrossWatch service should start a background sync.