For the complete documentation index, see llms.txt. This page is also available as Markdown.

Command-Line Interface (CLI)

Manage CrossWatch from a terminal with the cw command.

If you're more of a CLI kind of person, I've got you covered..

cw brings CrossWatch to your terminal.

It manages status, configuration, provider logins, syncs, Watcher, schedules, logs, and every major tool. The CLI runs in the CrossWatch container. It calls the running API.

Syncs started from the CLI appear in the web UI. They share its logs and running-sync guard.

Quick start

Run commands from the CrossWatch container.

docker exec -it crosswatch cw status
docker exec -it crosswatch cw auth setup --local --username admin
docker exec -it crosswatch cw sync run --follow

Use cw --help to list command groups. Use cw <group> --help for options and examples.

Run the CLI

Run cw inside the CrossWatch container:

docker exec -it crosswatch cw status
docker exec -it crosswatch cw sync run --follow
docker exec -it crosswatch cw shell

Inside the container, cw is on PATH:

cw status
cw auth token create --local

Outside Docker, run from the installation root:

CLI-only container mode

Set CW_CLI_ONLY=1 to keep the API, CLI, webhooks, and auth callbacks available.

This disables the CrossWatch web UI.

First setup

On a fresh install, set the admin password before using API commands:

This also creates and saves a CLI API token. Add --no-token to only set the password.

Tokens

Without application authentication, remote access only exposes health, status, and setup endpoints.

For CLI-only installs, run cw --local auth setup from the host or container. With authentication enabled, create a local token:

The token is shown once. The CLI saves it to /config/.cw_cli/cli.json in Docker.

Outside Docker, it uses ~/.crosswatch/cli.json.

For scripts and CI, write a token directly to a protected file:

The file is created with mode 0600. Only its ID, name, and expiry print. Existing files require --force to overwrite.

--format env writes CW_TOKEN=<token>.

On Linux and macOS, token files use mode 0600. Windows uses the destination folder's permissions. Store tokens in a folder only you can read.

Provide a token per command or through CW_TOKEN:

Tokens are hashed at rest. They inherit their user's permissions. Token actions enter the audit log. Use --expires-days to set an expiry.

Create a monitor token for scripts that only need read access:

--user accepts a user ID or username. Monitor tokens can read status, Watcher and scheduler state, pairs, run summaries, events, and captures across profiles.

They cannot write, view the audit log, or sign in to the web UI. Tokens created with --user are not saved locally unless you add --save.

Global options

Global options work before or after a subcommand.

  • -U, --url — Base URL. Uses CW_URL, then the local installation.

  • -T, --token — API token. Uses CW_TOKEN, then the saved token.

  • -o, --output — Output format: auto, table, json, yaml, or plain.

  • -L, --local — Use this installation. Never call the API.

  • -k, --insecure — Skip TLS checks for self-signed certificates.

  • --http-timeout — Request timeout in seconds. Default: 30.

  • -q, --quiet — Suppress non-essential output.

  • --no-color — Disable colour output.

Use -o json or -o plain in scripts. JSON is written to stdout. Errors are written to stderr.

Status

Use these commands to check the service and connected providers:

With --local, or when the service is unavailable, live state is unknown. This includes sync, Watcher, scheduler worker, and ready-to-sync state.

In JSON, watcher_alive, scheduler_running, sync_running, cancel_requested, and can_run are null.

Pairs

Create and manage synchronization pairs:

Use any unique pair-ID prefix. You can also use the route name.

--add-only creates each enabled feature with adding enabled and removal disabled.

Set individual options on an existing feature:

The first libraries form sets one provider's libraries. An empty value clears them. JSON replaces the complete scope.

cw pair show and cw pair set warn about mirror-mode features. This also applies when removal is disabled.

The check uses sync.one_way_remove_mode and sync.enable_remove defaults. In mirror mode, removal makes the target match the source.

With -o json, warnings appear in the warnings list.

Run a sync

Run and monitor synchronization:

cw sync run starts work through the running service. cw sync once runs locally, waits, and returns the sync result code.

Use cw sync once with docker run --rm, cron, or Kubernetes CronJobs. Unresolved items do not fail the command by default. Add --fail-on-unresolved for strict runs.

Use --plan-out PATH with --dry-run to write planned changes to JSON. Providers are still read, but no provider changes are written.

If planning fails or is cancelled, no file is written. Existing files remain unchanged. --fail-on-skipped cannot be combined with --plan-out.

The file contains one entry per pair under pairs. Each entry matches the Interactive Sync JSON download. Its rows list includes each item's feature, operation, result, and reason.

The command summary counts are calculated from those rows.

cw sync run --follow returns the underlying sync exit code.

Configuration

Read or change configuration values:

set uses a merge patch. It changes only the named key. Values parse as booleans, numbers, or null when applicable.

Use --json to replace an object or list. unset removes a key. Values under app_auth cannot be changed.

set accepts true, yes, on, numbers, and null as typed values. Other values remain strings.

Provider logins

Review available login flows before connecting:

cw auth login <provider> selects the required flow for supported CLI providers. Connect Kitsu, MyAnimeList, and WeTrakr through Settings → Connections; their login flows are not available in the CLI.

Plex, Trakt, SIMKL, MDBList, PunchPlay, BingeBase, and Nuvio use device codes.

They print a URL and code. The CLI polls until connected or timed out.

Jellyfin, Emby, Kodi, Stremio, Floppy, Scrob, Tautulli, PublicMetaDB, and TMDb require fields.

Trakt, SIMKL, and AniList require a client ID and secret first.

For scripted logins, supply fields and disable prompts:

Use cw auth show <provider> for supported field names. The provider prefix is optional. --non-interactive exits with code 2 when input is missing.

AniList then requires a browser approval. The CLI prints the URL and waits for its callback.

Use --instance <id> with commands that support multiple provider instances.

Analysis and events

Investigate mismatches and review recorded activity:

Most analyzer commands accept --pairs id1,id2.

Captures and backups

Captures provide point-in-time rollback:

capture create waits and prints progress. Add --no-wait to return immediately.

Media and playlists

Watchlists and playback

Manage watchlists, playback records, and editor data:

Editor

Playlists

Configure playlist resources, endpoints, mappings, and rules:

Linked-list syntax is being verified for this release. Until it is documented, use cw playlist resource --help in your installed build to confirm the supported link and profile arguments. Do not script an assumed URL option.

Import, metadata, and anime

Import and export

Use these commands for data exchange and item matching:

Export to Trakt

Use --format trakt to create a Trakt movie CSV export:

The preview reports unsupported items and invalid data. Trakt exports support movies with valid IMDb IDs.

Use a .zip output when repeated movie IDs need separate CSV files. Use .csv when one file is enough.

The CLI preserves the response bytes. The web UI selects the extension automatically.

Extract ZIP downloads before importing them into Trakt. Upload numbered CSV files individually and in order.

Metadata and manual entries

Anime mapping

Instances, profiles, and scrobbling

Instances and profiles

Manage provider instances, user profiles, and scrobbling routes:

Access levels are readonly, full, and monitor. --profile accepts a profile ID or name. Every user needs a profile.

Without --password or --ask-password, cw user create assigns an unknown random password. The account then only works with an API token.

Monitor accounts are always token-only. Only the CLI can assign the monitor access level.

Scrobbling

Reporting and maintenance

Reporting

Review local activity, then run maintenance when needed:

Maintenance

Maintenance commands can delete local data or restart CrossWatch.

Watcher, scheduler, and logs

Watcher

Control background services and inspect their output:

Scheduler

Logs

Interactive shell

Run cw shell to open an interactive prompt.

? lists commands in the current group. Use help <command> for detailed help. Use exit, end, or .. to move back.

History is saved to ~/.crosswatch/history. Tab completion works where readline is available.

Exit codes

cw sync run --follow returns the sync's exit code instead.

When the service is down

Supported read-only and repair commands fall back to the local installation. The CLI writes a notice to stderr and reports local (fallback) as the endpoint.

The fallback supports status, health, version, all config commands, pair list/show/enable/disable/delete, sync list, scheduler status/next/show, and all auth token commands.

Commands requiring the running engine fail with exit code 3. This includes syncs, Watcher actions, and live logs. --local forces this mode and rejects unsupported commands immediately.

Last updated

Was this helpful?