CLI Reference

What the CLI Does

The synctv binary can start the service and act as an administrative CLI.

It supports:

Local operations: load configuration, validate configuration, run database migrations, and start the service.
Management operations: manage users, rooms, providers, settings, and system state through the management gRPC endpoint.
Helper operations: generate shell completions and print version information.

General help:

synctv --help

Command help:

synctv --help

synctv user --help

synctv room playback --help

synctv provider alist --help

For operational semantics, read Administration Runbook. Before changing room roles, permission bits, room settings, or user preferences, read Rooms, Permissions, and Preferences.

Global Flags

`--config <PATH>`

Explicit configuration file:

synctv --config /etc/synctv/synctv.yaml config validate

This has higher precedence than default search paths and SYNCTV_CONFIG_PATH.

`--data-dir <PATH>`

Override runtime data directory:

synctv --data-dir /var/lib/synctv serve

This affects management socket, HLS storage, slice cache, file logs, and similar runtime-owned paths. It does not affect *_file secret paths.

`--no-dotenv`

Do not load .env:

synctv --no-dotenv config validate

Useful in CI and production scripts where configuration should come only from explicit files and environment variables.

`-v` / `--verbose`

Print more detailed configuration loading diagnostics:

synctv -v config validate

`--endpoint <ENDPOINT>`

Management endpoint.

Unix socket:

synctv --endpoint unix:///var/lib/synctv/synctv.sock system stats

TCP:

synctv --endpoint http://127.0.0.1:50052 system stats

Environment variable:

SYNCTV_MANAGEMENT_ENDPOINT=http://127.0.0.1:50052

`--auth-token` and `--auth-token-file`

TCP management requires a bearer token.

synctv --endpoint http://127.0.0.1:50052 --auth-token "$TOKEN" system stats

Prefer file input:

synctv --endpoint http://127.0.0.1:50052 --auth-token-file /run/secrets/management_token system stats

Environment variables:

SYNCTV_MANAGEMENT_AUTH_TOKEN=...
SYNCTV_MANAGEMENT_AUTH_TOKEN_FILE=/run/secrets/management_token

Output Formats

Remote management commands commonly support:

--output human
--output json
--output yaml

Example:

synctv user list --output json

Configuration output supports:

--output yaml
--output json
--output toml

synctv config show --output json

Service Commands

Start service:

synctv serve
synctv serve --config synctv.yaml

Dry-run startup:

synctv serve --dry-run

Stop a running service through management:

synctv stop
synctv stop --force

--force asks for faster shutdown and reduces drain waiting.

Configuration Commands

Validate effective configuration:

synctv config validate
synctv --config /etc/synctv/synctv.yaml config validate

Show merged configuration with secrets redacted:

synctv config show
synctv config show --output json

Database Commands

Run embedded SQLx migrations without starting the service. Startup runs the same migrations automatically, so this command is mainly for preflight, CI, test environments, and troubleshooting:

synctv db migrate

Check database connectivity and migration state:

synctv db status
synctv db status --output yaml

User Management

Common commands:

synctv user list
synctv user get alice
synctv user create alice --password 'StrongPass123'
synctv user delete alice
synctv user ban alice --reason "abuse"
synctv user unban alice
synctv user set-role alice admin
synctv user set-password alice --password 'NewStrongPass123'
synctv user set-username alice --username alice2
synctv user rooms alice

Preferences:

synctv user preferences get alice
synctv user preferences set alice --two-factor-enabled true

Admin role:

synctv user admin grant alice
synctv user admin revoke alice
synctv user admin list

Batch operations:

synctv user batch ban alice bob --reason "spam"
synctv user batch delete alice bob

Privileged operations follow role hierarchy. A non-root admin cannot modify root or higher-privilege users’ sensitive settings.

Room Management

Rooms:

synctv room create "Movie Room" --username alice
synctv room list
synctv room get <ROOM_ID>
synctv room set-password <ROOM_ID> --password "room-pass"
synctv room transfer-owner <ROOM_ID> --username alice bob
synctv room ban <ROOM_ID> --reason "policy"
synctv room unban <ROOM_ID>
synctv room delete <ROOM_ID>

Room settings:

synctv room settings get <ROOM_ID>
synctv room settings update <ROOM_ID> --settings-json '{"join_requires_review":true}'
synctv room settings reset <ROOM_ID>

Members:

synctv room member list <ROOM_ID>
synctv room member add <ROOM_ID> alice
synctv room member set-permissions <ROOM_ID> alice --role admin
synctv room member kick <ROOM_ID> alice
synctv room member ban <ROOM_ID> alice
synctv room member unban <ROOM_ID> alice

Playback:

synctv room playback get <ROOM_ID>
synctv room playback start --room-id <ROOM_ID> --media-id <MEDIA_ID>
synctv room playback play <ROOM_ID>
synctv room playback pause <ROOM_ID>
synctv room playback seek --room-id <ROOM_ID> --position 60
synctv room playback speed <ROOM_ID> --speed 1.25
synctv room playback stop <ROOM_ID>

Streams:

synctv room stream list <ROOM_ID>

Reviews and Bans

User registration review:

synctv review user-registration list
synctv review user-registration approve <REVIEW_ID>
synctv review user-registration reject <REVIEW_ID> --reason "reason"

Room creation review:

synctv review room-creation list
synctv review room-creation approve <REVIEW_ID>
synctv review room-creation reject <REVIEW_ID> --reason "reason"

Room join review:

synctv review room-join list
synctv review room-join approve <REVIEW_ID>
synctv review room-join reject <REVIEW_ID> --reason "reason"

Ban records:

synctv ban list

Playlists and Media

Playlists:

synctv playlist list <ROOM_ID>
synctv playlist get <ROOM_ID> <PLAYLIST_ID>
synctv playlist create --room-id <ROOM_ID> --username alice "Weekend List"
synctv playlist update --room-id <ROOM_ID> <PLAYLIST_ID> --name "New Title"
synctv playlist move --room-id <ROOM_ID> <PLAYLIST_ID> --after-playlist-id <OTHER_PLAYLIST_ID>
synctv playlist delete <ROOM_ID> <PLAYLIST_ID>

Media:

synctv media list <ROOM_ID>
synctv media add-url --room-id <ROOM_ID> --username alice "https://example.com/video.mp4" --title "Video"
synctv media add --room-id <ROOM_ID> --username alice --source-config-json '{"url":"https://example.com/video.mp4"}' --title "Video"
synctv media update --room-id <ROOM_ID> <MEDIA_ID> --title "New Title"
synctv media move --room-id <ROOM_ID> <MEDIA_ID> --after-media-id <OTHER_MEDIA_ID>
synctv media delete <ROOM_ID> <MEDIA_ID>

Provider-backed media:

synctv playlist provider alist <ROOM_ID> ...
synctv playlist provider emby <ROOM_ID> ...
synctv media provider alist <ROOM_ID> ...
synctv media provider emby <ROOM_ID> ...
synctv media provider bilibili video <ROOM_ID> ...
synctv media provider bilibili pgc <ROOM_ID> ...
synctv media provider bilibili live <ROOM_ID> ...

Use --help for exact provider-specific arguments.

Provider Management

Provider instances:

synctv provider available
synctv provider backends alist
synctv provider list
synctv provider create <NAME> <PROVIDER_ENDPOINT> --provider alist
synctv provider update <NAME> --provider-endpoint <PROVIDER_ENDPOINT> --provider alist
synctv provider enable <NAME>
synctv provider disable <NAME>
synctv provider reconnect <NAME>
synctv provider delete <NAME>

Alist:

synctv provider alist login --username alice --host https://alist.example --account-username alice --password 'pass' --instance-name alist-main
synctv provider alist list --username alice --path / --instance-name alist-main
synctv provider alist search --username alice --keyword movie --instance-name alist-main
synctv provider alist me --username alice --instance-name alist-main
synctv provider alist binds --username alice
synctv provider alist logout --username alice --instance-name alist-main

Emby:

synctv provider emby login --username alice --host https://emby.example --account-username alice --password 'pass' --instance-name emby-main
synctv provider emby list --username alice --instance-name emby-main
synctv provider emby me --username alice --instance-name emby-main
synctv provider emby binds --username alice
synctv provider emby logout --username alice --instance-name emby-main

Bilibili:

synctv provider bilibili parse "https://www.bilibili.com/video/..."
synctv provider bilibili login-qr --username alice --instance-name bilibili-main
synctv provider bilibili check-qr --username alice --key <KEY> --instance-name bilibili-main
synctv provider bilibili get-captcha --username alice --instance-name bilibili-main
synctv provider bilibili send-sms --username alice --phone 13800000000 --token <TOKEN> --challenge <CHALLENGE> --validate <VALIDATE> --instance-name bilibili-main
synctv provider bilibili login-sms --username alice --phone 13800000000 --code 123456 --captcha-key <CAPTCHA_KEY> --instance-name bilibili-main
synctv provider bilibili me --username alice --instance-name bilibili-main
synctv provider bilibili binds --username alice
synctv provider bilibili logout --username alice --instance-name bilibili-main

RTMP:

synctv provider rtmp create-publish-key --username alice --room-id <ROOM_ID> <MEDIA_ID>
synctv provider rtmp info --username alice --room-id <ROOM_ID> <MEDIA_ID>

Runtime Settings

Runtime settings are changed through the management endpoint. They are not the same as YAML startup configuration.

synctv settings list
synctv settings get email
synctv settings update email --set whitelist_enabled=true --set whitelist=example.com
synctv settings test-email admin@example.com

See Runtime Settings Reference for all keys, defaults, and validation rules.

SMTP host, port, username, password, and sender identity are startup configuration, not runtime settings. settings test-email sends through the SMTP configuration loaded by the running service.

Security note: do not expose the management TCP endpoint publicly. Use strong tokens and prefer internal networks or VPNs.

System and Slice Cache

System state:

synctv system stats
synctv system stream list
synctv system stream kick <STREAM_ID>

Slice cache operations:

synctv slice-cache stats
synctv slice-cache evict-expired
synctv slice-cache purge

Slice cache enablement is controlled by startup config cache.proxy_slice_cache_enabled. CLI operations only provide stats, cleanup, and expiration eviction.

Shell Completions

synctv completion bash > synctv.bash
synctv completion zsh > _synctv
synctv completion fish > synctv.fish

Installation paths depend on the shell and OS distribution.

Version

synctv version