Administration Runbook

Purpose

The CLI Reference lists commands. This page explains their operational meaning, ordering, and risk. Production administrators usually manage users, rooms, reviews, providers, runtime settings, system state, and cache cleanup through the management gRPC control plane.

Control Plane Boundary

Management gRPC is an operational control plane, not a normal user API.

Production guidance:

• Prefer Unix socket transport.
• TCP management must set management.auth_token.
• Do not expose TCP management publicly.
• Remote administration should go through private networks, VPNs, bastions, or Kubernetes exec.
• Operations involving root/admin users, security preferences, or provider credentials should be auditable.

Common connection methods:

Unix socket

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

TCP

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

User Management

Users have a global role and an effective status:

Concept	Values	Meaning
Global role	root, admin, user	Platform-level management capability
Effective status	active, banned	Derived from ban records; affects login, room creation, and joining
Preferences	2FA, notifications, provider defaults	User-level settings, not YAML configuration

Role hierarchy:

• root can manage all users and administrators.
• admin can manage normal users but cannot modify root or equally privileged admins.
• user can use rooms and media features according to business permissions.

Common operations:

synctv user list
synctv user get alice
synctv user create alice --password 'StrongPass123'
synctv user ban alice --reason "abuse"
synctv user unban alice
synctv user set-role alice admin
synctv user preferences get alice

Security guidance:

• Prefer ban over delete unless you intentionally want to remove related data.
• Password, role, and 2FA preference changes are sensitive operations.
• Enabling 2FA requires at least two local methods. OAuth2 is not counted as a local 2FA factor.

Room Management

Room operations fall into lifecycle, members, settings, playback, and livestreaming.

Category	Commands	Risk
Lifecycle	room create, room delete, room ban, room transfer-owner	Affects visibility, ownership, and data retention
Members	room member add/kick/ban/unban/set-permissions	Changes access and management ability
Settings	room settings update/reset	Changes join rules, guests, chat, danmaku, and permission defaults
Playback	room playback play/pause/seek/start/stop	Changes playback state for online members
Livestream	room stream list, provider rtmp create-publish-key	Involves stream keys and livestream sessions

Recommended flow:

1. Query current room and member state first.
2. Confirm actor, target user, and room role before modifying anything.
3. Grant only required member permissions. Do not delegate DELETE_ROOM as a room-scoped capability.
4. After room settings changes, verify WebSocket sync and join behavior.
5. Keep reasons for delete, ban, ownership transfer, and rejection operations.

Reviews and Bans

Review queues cover:

• User registration.
• Room creation.
• Room join requests.

Example:

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

Recommendations:

• Use clear reasons for rejections and bans.
• Before bulk bans, use user list or room member list to confirm targets.
• User bans affect login, room creation, and joining. Room-member bans affect only the target room.

Provider Management

Provider instances are connection configurations for external media sources. They may contain URLs, tokens, cookies, user agents, authentication data, remote gRPC settings, or backend-specific parameters.

Common operations:

synctv provider available
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>

Production guidance:

• Prefer secret files, encrypted storage, or controlled management APIs for credentials.
• After changing provider headers, UA, or proxy policy, test both direct and proxy paths.
• Header-sensitive providers such as Bilibili and Alist require special attention to User-Agent, Referer, Range, and authentication headers.
• Before deleting an instance, check whether user preferences or room media still reference it.

Runtime Settings

Runtime settings are hot-reload database settings. They are not YAML startup configuration.

synctv settings list
synctv settings get user.enable_password_signup
synctv settings update user --set enable_password_signup=true

Semantics:

• Persisted in PostgreSQL.
• Propagated across replicas through PostgreSQL LISTEN/NOTIFY.
• Validated by registered setting providers.
• Suitable for registration, room creation, proxy policy, and CORS runtime switches.
• Not suitable for startup secrets, listener ports, database URLs, or Redis URLs.

See Runtime Settings Reference for all keys.

System and Cache Operations

System state:

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

Slice cache:

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

Notes:

• Slice cache enablement is controlled by startup setting cache.proxy_slice_cache_enabled.
• The CLI cannot dynamically enable or disable slice cache. It only provides stats, expired eviction, and purge operations.
• purge removes cache data and lowers future hit rate, but does not affect durable PostgreSQL business data.

Before You Operate

Understand Semantics

If command impact is unclear, read this page and Rooms, Permissions, and Preferences before checking flags.

Inspect State

Before delete, ban, transfer, or bulk operations, run list/get commands and confirm targets.

Keep Reasons

Use reasons for rejection, ban, kick, and delete operations to reduce audit cost.

Verify Results

After changes, check API, WebSocket, provider behavior, metrics, or logs.