# Adapter: CrossWatch

CrossWatch adapter is a **local backup provider**. It stores watchlist, history, and ratings as JSON in your config folder.

Use it as a safety net:

* Backup: `Plex/Emby/Jellyfin/Trakt/SIMKL/MDBList/TMDb → CrossWatch`
* Restore: `CrossWatch → any provider`

{% hint style="info" %}
Nothing runs “automatically”. CrossWatch adapter only does work when it’s used in a pair.
{% endhint %}

### What it supports

* Features: **Watchlist**, **History**, **Ratings**
* Auth: none (local only)
* Storage:
  * Current state: `/config/.cw_provider/`
  * Snapshots: `/config/.cw_provider/snapshots/`
* Restore granularity: per feature (pick different snapshots per feature)

### Storage layout

Current state files:

* `/config/.cw_provider/watchlist.json`
* `/config/.cw_provider/history.json`
* `/config/.cw_provider/ratings.json`

Snapshots are timestamped:

* `YYYYMMDDThhmmssZ-watchlist.json`
* `YYYYMMDDThhmmssZ-history.json`
* `YYYYMMDDThhmmssZ-ratings.json`

### When snapshots are created

Snapshots are only created when CrossWatch needs to **change** its local data.

Typical case:

* CrossWatch is the **target** in a run.
* The run applies add/remove operations.
* If **Auto snapshot** is enabled, CrossWatch snapshots the old state first.

### Settings

Go to **Settings → CrossWatch Tracker**.

#### Basic behavior

* **Enabled**: toggles the provider for use in pairs.
* **Retention (days)**: `0` keeps snapshots forever.
* **Auto snapshot**: snapshots before writes.
* **Max snapshots per feature**: `0` = unlimited.

#### Restore snapshots (per feature)

Pick one snapshot for each feature:

* Watchlist snapshot
* History snapshot
* Ratings snapshot

`Latest (default)` uses the most recent snapshot for that feature.

<details>

<summary>What gets written to config</summary>

```jsonc
"crosswatch": {
  "enabled": true,
  "retention_days": 30,
  "auto_snapshot": true,
  "max_snapshots": 64,
  "restore_watchlist": "latest",
  "restore_history": "latest",
  "restore_ratings": "latest"
}
```

</details>

### What “restore” means

Selecting a snapshot does **not** push changes to other providers.

It only changes what CrossWatch exposes as its **current state**:

* The chosen snapshot is copied into the main JSON for that feature.
* A restore happens only when you run a pair where CrossWatch is the **source**.

{% hint style="warning" %}
Snapshot selection “arms” the restore. Running a pair “applies” the restore.
{% endhint %}

### Common workflows

{% stepper %}
{% step %}

### Undo a bad sync (restore ratings)

1. Open **Settings → CrossWatch Tracker**.
2. Set **Ratings snapshot** to a time before the bad run.
3. **Save**.
4. Run a pair: **CrossWatch → target provider**, enable **Ratings** only.
   {% endstep %}

{% step %}

### Roll back watchlist only

1. Set **Watchlist snapshot** to an older file.
2. Keep History/Ratings on **Latest**.
3. Run a pair: **CrossWatch → target provider**, enable **Watchlist** only.
   {% endstep %}

{% step %}

### Migrate state to a new provider

1. Pick snapshots you trust for the features you want.
2. Run a pair: **CrossWatch → new provider**.
3. Start one-way first. Use one feature. Then expand.
   {% endstep %}
   {% endstepper %}

### Tips and limitations

* CrossWatch is **local**. Remove `/config/.cw_provider/` and you lose backups.
* Low retention + frequent runs will prune older snapshots quickly.
* This is extra protection. It does not replace provider-side backups (if any).

Recommended baseline:

* Enabled: **On**
* Auto snapshot: **On**
* Retention: **30–90** days
* Max snapshots per feature: **64**
* Restore selection: **Latest**, until you need a rollback


---

# Agent Instructions: 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:

```
GET https://wiki.crosswatch.app/crosswatch/providers/synchronization/adapter-crosswatch.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.