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.
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 --followUse 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 shellInside the container, cw is on PATH:
cw status
cw auth token create --localOutside 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.
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.
Global options
Global options work before or after a subcommand.
-U,--url— Base URL. UsesCW_URL, then the local installation.-T,--token— API token. UsesCW_TOKEN, then the saved token.-o,--output— Output format:auto,table,json,yaml, orplain.-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:
Pairs
Create and manage synchronization pairs:
Use any unique pair-ID prefix. You can also use the route name.
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.
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.
Provider logins
Review available login flows before connecting:
cw auth login <provider> selects the required flow:
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:
Always run cw playlist mapping run <id> --dry-run before a live mapping run.
Import, metadata, and anime
Import and export
Use these commands for data exchange and item matching:
Metadata and manual entries
Anime mapping
Instances, profiles, and scrobbling
Instances and profiles
Manage provider instances, user profiles, and scrobbling routes:
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
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.
CLI layout
To add a group, create commands/<name>.py with register(app). List it in _app._register_all. Commands use Ctx, which provides automatic local fallback.
Last updated
Was this helpful?