CLI 参考
CLI 用来做什么？
Section titled “CLI 用来做什么？”synctv 二进制既可以启动服务，也可以作为管理 CLI 使用。
它支持三类操作：
- 本地操作：读取配置、校验配置、执行数据库迁移、启动服务。
- 管理操作：通过 management gRPC 端点管理用户、房间、Provider、系统状态等。
- 辅助操作：生成 shell completions、查看版本。
查看总帮助：
synctv --help查看某个命令帮助：
synctv --helpsynctv user --helpsynctv room playback --helpsynctv provider alist --help如果你要理解管理动作的业务语义，先看 管理员操作手册。如果你要修改房间角色、权限位、房间设置或用户偏好，先看 房间、权限与用户偏好。
这些参数可以放在多数子命令前后。
--config <PATH>
Section titled “--config <PATH>”显式指定配置文件路径。
synctv --config /etc/synctv/synctv.yaml config validate优先级高于默认搜索路径和 SYNCTV_CONFIG_PATH。
--data-dir <PATH>
Section titled “--data-dir <PATH>”覆盖运行时数据目录。
synctv --data-dir /var/lib/synctv serve影响管理 socket、HLS 存储、slice cache、文件日志等运行时输出路径，但不影响 *_file secret 文件路径。
--no-dotenv
Section titled “--no-dotenv”不加载 .env。
synctv --no-dotenv config validate适合 CI、生产脚本或你希望完全由环境变量/配置文件控制时使用。
-v / --verbose
Section titled “-v / --verbose”输出更详细的配置加载诊断。
synctv -v config validate--endpoint <ENDPOINT>
Section titled “--endpoint <ENDPOINT>”指定 management 端点。
Unix socket 示例：
synctv --endpoint unix:///var/lib/synctv/synctv.sock system statsTCP 示例：
synctv --endpoint http://127.0.0.1:50052 system stats也可以使用环境变量：
SYNCTV_MANAGEMENT_ENDPOINT=http://127.0.0.1:50052--auth-token 和 --auth-token-file
Section titled “--auth-token 和 --auth-token-file”TCP management 端点需要 bearer token。
synctv --endpoint http://127.0.0.1:50052 --auth-token "$TOKEN" system stats推荐从文件读取：
synctv --endpoint http://127.0.0.1:50052 --auth-token-file /run/secrets/management_token system stats也可以使用：
SYNCTV_MANAGEMENT_AUTH_TOKEN=...SYNCTV_MANAGEMENT_AUTH_TOKEN_FILE=/run/secrets/management_token远程管理命令通常支持：
--output human--output json--output yaml
示例：
synctv user list --output json配置展示支持：
--output yaml--output json--output toml
示例：
synctv config show --output json启动 SyncTV 服务。
synctv servesynctv serve --config synctv.yaml只校验并演练启动流程：
synctv serve --dry-run通过 management 端点停止运行中的服务。
synctv stopsynctv stop --force--force 会请求更快关闭，减少 drain 等待时间。
config validate
Section titled “config validate”校验最终配置。
synctv config validatesynctv --config /etc/synctv/synctv.yaml config validateconfig show
Section titled “config show”输出合并后的配置，secret 会被隐藏。
synctv config showsynctv config show --output jsondb migrate
Section titled “db migrate”显式运行 embedded SQLx migrations 但不启动服务。服务启动阶段也会自动执行同一套 migrations，因此这个命令主要用于预检、CI、测试环境和排障。
synctv db migratedb status
Section titled “db status”检查数据库连接和迁移状态。
synctv db statussynctv db status --output yaml用户命令用于管理用户生命周期、角色、密码、偏好和批量操作。
常见命令：
synctv user listsynctv user get alicesynctv user create alice --password 'StrongPass123'synctv user delete alicesynctv user ban alice --reason "abuse"synctv user unban alicesynctv user set-role alice adminsynctv user set-password alice --password 'NewStrongPass123'synctv user set-username alice --username alice2synctv user rooms alice用户偏好：
synctv user preferences get alicesynctv user preferences set alice --two-factor-enabled true管理员角色：
synctv user admin grant alicesynctv user admin revoke alicesynctv user admin list批量操作：
synctv user batch ban alice bob --reason "spam"synctv user batch delete alice bob注意：涉及 root/admin 的操作会遵守角色层级，普通 admin 不能越权修改 root 或其他高权限用户的敏感设置。
房间命令覆盖房间创建、查询、成员、设置、播放和直播状态。
常见命令：
synctv room create "电影房" --username alicesynctv room listsynctv room get <ROOM_ID>synctv room set-password <ROOM_ID> --password "room-pass"synctv room transfer-owner <ROOM_ID> --username alice bobsynctv room ban <ROOM_ID> --reason "policy"synctv room unban <ROOM_ID>synctv room delete <ROOM_ID>房间设置：
synctv room settings get <ROOM_ID>synctv room settings update <ROOM_ID> --settings-json '{"join_requires_review":true}'synctv room settings reset <ROOM_ID>成员管理：
synctv room member list <ROOM_ID>synctv room member add <ROOM_ID> alicesynctv room member set-permissions <ROOM_ID> alice --role adminsynctv room member kick <ROOM_ID> alicesynctv room member ban <ROOM_ID> alicesynctv room member unban <ROOM_ID> alice播放控制：
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 60synctv room playback speed <ROOM_ID> --speed 1.25synctv room playback stop <ROOM_ID>直播流：
synctv room stream list <ROOM_ID>审核命令：
synctv review user-registration listsynctv review user-registration approve <REVIEW_ID>synctv review user-registration reject <REVIEW_ID> --reason "reason"
synctv review room-creation listsynctv review room-creation approve <REVIEW_ID>synctv review room-creation reject <REVIEW_ID> --reason "reason"
synctv review room-join listsynctv review room-join approve <REVIEW_ID>synctv review room-join reject <REVIEW_ID> --reason "reason"封禁记录：
synctv ban list播放列表与媒体
Section titled “播放列表与媒体”播放列表：
synctv playlist list <ROOM_ID>synctv playlist get <ROOM_ID> <PLAYLIST_ID>synctv playlist create --room-id <ROOM_ID> --username alice "周末片单"synctv playlist update --room-id <ROOM_ID> <PLAYLIST_ID> --name "新标题"synctv playlist move --room-id <ROOM_ID> <PLAYLIST_ID> --after-playlist-id <OTHER_PLAYLIST_ID>synctv playlist delete <ROOM_ID> <PLAYLIST_ID>媒体：
synctv media list <ROOM_ID>synctv media add-url --room-id <ROOM_ID> --username alice "https://example.com/video.mp4" --title "视频"synctv media add --room-id <ROOM_ID> --username alice --source-config-json '{"url":"https://example.com/video.mp4"}' --title "视频"synctv media update --room-id <ROOM_ID> <MEDIA_ID> --title "新标题"synctv media move --room-id <ROOM_ID> <MEDIA_ID> --after-media-id <OTHER_MEDIA_ID>synctv media delete <ROOM_ID> <MEDIA_ID>Provider 相关添加：
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> ...具体参数以 --help 输出为准。
Provider 管理
Section titled “Provider 管理”Provider 实例管理：
synctv provider availablesynctv provider backends alistsynctv provider listsynctv provider create <NAME> <PROVIDER_ENDPOINT> --provider alistsynctv provider update <NAME> --provider-endpoint <PROVIDER_ENDPOINT> --provider alistsynctv 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-mainsynctv provider alist list --username alice --path / --instance-name alist-mainsynctv provider alist search --username alice --keyword movie --instance-name alist-mainsynctv provider alist me --username alice --instance-name alist-mainsynctv provider alist binds --username alicesynctv provider alist logout --username alice --instance-name alist-mainEmby 服务操作：
synctv provider emby login --username alice --host https://emby.example --account-username alice --password 'pass' --instance-name emby-mainsynctv provider emby list --username alice --instance-name emby-mainsynctv provider emby me --username alice --instance-name emby-mainsynctv provider emby binds --username alicesynctv provider emby logout --username alice --instance-name emby-mainBilibili 服务操作：
synctv provider bilibili parse "https://www.bilibili.com/video/..."synctv provider bilibili login-qr --username alice --instance-name bilibili-mainsynctv provider bilibili check-qr --username alice --key <KEY> --instance-name bilibili-mainsynctv provider bilibili get-captcha --username alice --instance-name bilibili-mainsynctv provider bilibili send-sms --username alice --phone 13800000000 --token <TOKEN> --challenge <CHALLENGE> --validate <VALIDATE> --instance-name bilibili-mainsynctv provider bilibili login-sms --username alice --phone 13800000000 --code 123456 --captcha-key <CAPTCHA_KEY> --instance-name bilibili-mainsynctv provider bilibili me --username alice --instance-name bilibili-mainsynctv provider bilibili binds --username alicesynctv provider bilibili logout --username alice --instance-name bilibili-mainRTMP：
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
Section titled “Runtime settings”运行时设置通过 management 端点修改，不等同于 YAML 启动配置。
synctv settings listsynctv settings get emailsynctv settings update email --set whitelist_enabled=true --set whitelist=example.comsynctv settings test-email admin@example.com完整 key、默认值和校验规则见 Runtime settings 参考。
SMTP 主机、端口、账号、密码和发件人属于启动配置，不是 runtime settings。settings test-email 使用当前服务启动时加载的 SMTP 配置发送测试邮件。
安全建议：不要把 management TCP 端点暴露公网。远程执行时使用强 token，并优先通过内网或 VPN 访问。
系统与 slice cache
Section titled “系统与 slice cache”系统状态：
synctv system statssynctv system stream listsynctv system stream kick <STREAM_ID>slice cache 运维：
synctv slice-cache statssynctv slice-cache evict-expiredsynctv slice-cache purge注意：slice cache 是否启用由启动配置 cache.proxy_slice_cache_enabled 决定，不支持通过 CLI 动态启停。CLI 只提供统计、清理和过期驱逐。
Shell completions
Section titled “Shell completions”生成 shell completion：
synctv completion bash > synctv.bashsynctv completion zsh > _synctvsynctv completion fish > synctv.fish具体安装路径取决于你的 shell 和系统发行版。
synctv version