Manage registered plugin hosts

These commands edit the server configuration. Restart the server to apply changes.

Manage plugin hostsCopy Anchor Link

plugins registers remote plugin hosts in the pluginHosts section of your configuration, so you do not have to edit the JSON by hand. The configuration file stays the only source of truth: there is no separate database, lockfile or install directory.

The commands only edit configuration, so they work without FFmpeg and never start the server, the playback runtime or any Discord connection. They honor --config (default ./remedia.config.json), --env-file and --optional-env-file, and they never create a configuration: if the file is missing they point you to --generate-config-file.

Changes are written to the file, not to a running server. Restart remedia-server to apply them.

Install a public hostCopy Anchor Link

remedia-server plugins install https://plugins.example.com

The command fetches /.well-known/remedia, validates it with the same rules the server uses, shows the host and every (pluginId, operation) pair it advertises, and asks which to allow. The host ID is the manifest's hostId when it declares one. Otherwise it is derived from the display name or hostname, or set with --id. A declared hostId always wins, and a conflicting --id is an error. Existing registrations with the same ID or the same endpoint are refused.

Choose operations without prompts for scripts:

remedia-server plugins install https://plugins.example.com \
  --id media-host \
  --operation example.source/source.stream \
  --operation example.metadata/catalog.search \
  --yes

• --operation PLUGIN/OPERATION (repeatable) allows exactly those operations. The host must advertise them.
• --all-operations acknowledges and allows everything the host advertises.
• Without one of them a noninteractive session fails, because Remedia never enables advertised operations silently. Without --yes a noninteractive session also fails, because nothing is written unconfirmed.
• --replay-safe PLUGIN/OPERATION marks an allowed operation as safe to retry. It is off by default, and the host's own claims are never trusted: this is an operator decision.
• --dry-run prints the entry and validates the result without writing.

Install an authenticated hostCopy Anchor Link

export REMEDIA_PLUGIN_TOKEN='a-long-random-token'
remedia-server plugins install https://plugins.example.com --token-env REMEDIA_PLUGIN_TOKEN

The file receives the reference, never the secret:

{ "auth": { "type": "bearer", "token": "env('REMEDIA_PLUGIN_TOKEN')" } }

The variable is resolved with the usual precedence (process environment, then --env-file files) only to authenticate discovery. Remedia does not create or modify .env files and never prints tokens. A host that requires authentication, or rejects the token, produces an actionable error.

Local and cleartext hostsCopy Anchor Link

Install local hosts directly:

remedia plugins install http://localhost:5678

The CLI discovers the manifest, infers the host ID, asks which operations to authorize and confirms the write. HTTP URLs automatically produce allowHttp: true; explicitly configured localhost and LAN hosts need no additional flags. Noninteractive installs require --operation PLUGIN/OPERATION (repeatable) or --all-operations, plus --yes. Replay safety defaults to false. URLs may not contain credentials, paths, queries or fragments. Redirects are never followed; requests remain bounded in size and time.

Connection diagnostics distinguish refusal, DNS failure, likely scheme mismatch, TLS validation, timeout, blocked destination, authentication failure and incompatible manifests where detectable. No raw transport error or media grant URL is printed. Check plugins inspect HOST --check and doctor for live status; an advertised operation still needs explicit authorization.

List and inspectCopy Anchor Link

remedia-server plugins list
remedia-server plugins list --json
remedia-server plugins inspect media-host
remedia-server plugins inspect media-host --check

list and inspect read only the file, so they show what is configured, not whether a host is healthy. inspect --check contacts the host and reports protocol compatibility, authentication, reachability and allowed operations which are no longer advertised. It exits with 2 when it finds a problem. JSON output is stable and contains no credentials: a token appears only as the name of its environment variable (tokenEnv) or as "tokenSource": "inline".

Enable and disableCopy Anchor Link

remedia-server plugins disable media-host
remedia-server plugins enable media-host

A disabled host keeps its endpoint, credentials, operations and limits ("enabled": false), but the server does not register it at startup: it is not discovered or listed, and requests naming it fail with plugin_host_disabled instead of using another host. Omitting enabled means enabled.

SynchronizeCopy Anchor Link

remedia-server plugins sync
remedia-server plugins sync media-host
remedia-server plugins sync media-host --apply

sync fetches each host's manifest and prints a diff: - marks allowed operations the host no longer advertises, + marks newly advertised ones. By default it is read-only and exits with 2 when it found differences or could not check a host. A host that is unreachable or incompatible is reported and its configuration is left alone.

--apply asks about each change in an interactive session. Newly advertised operations are never enabled implicitly, are added with replaySafe: false, and existing replaySafe values, identities and authentication are never changed. For automation, name the changes explicitly:

remedia-server plugins sync media-host --apply \
  --add example.metadata/lyrics.search --remove-missing --yes

UninstallCopy Anchor Link

remedia-server plugins uninstall media-host
remedia-server plugins uninstall media-host --yes

Shows the host and the operations being removed, then removes only that entry. Unrelated configuration is untouched, the remote service is never contacted, and removing a host that is not configured is an error. --dry-run previews the change.

How the file is editedCopy Anchor Link

Edits splice text into the file, so unrelated fields (including $schema), key order, indentation, line endings and the trailing newline are preserved. The complete resulting configuration is validated before it is written to a temporary file and renamed over the original. If the file changed since it was read, nothing is written. Environment variables used by unrelated settings do not need to be set to run these commands. They are checked for shape only.

Exit codes: 0 success, 1 failure, 2 for sync and inspect --check when they found something that needs attention.