> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/advanced-and-api/crosswatch-cli/container-run-once-mode.md). # Container Run Once Mode `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. {% hint style="info" %} 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. {% endhint %} ### Start a sync Run all enabled sync pairs: ```shell cw sync once ``` Run one pair by its number, ID, unique ID prefix, or label: ```shell cw sync once 1 ``` ```shell cw sync once pair_07c3 ``` Run several pairs: ```shell cw sync once --pair pair_07c3 --pair pair_91ab ``` Run only specific features: ```shell cw sync once --feature watchlist ``` ```shell 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: ```shell 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. ```shell cw sync once --json ``` Combine it with pair selection when needed: ```shell 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: ```shell cw sync once --fail-on-unresolved ``` Fail when CrossWatch skips an item: ```shell cw sync once --fail-on-skipped ``` Combine both checks: ```shell 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: ```shell 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. ```shell docker run --rm \ -v crosswatch_config:/config \ -e TZ=Europe/Amsterdam \ ghcr.io/cenodude/crosswatch:latest \ cw sync once ``` Select specific pairs: ```shell 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: ```shell 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://wiki.crosswatch.app/crosswatch/advanced-and-api/crosswatch-cli/container-run-once-mode.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.