Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

symposium use

Enable a plugin by name, and sync it into the workspace immediately.

Usage

symposium use <NAME> [--global]
symposium use <NAME> --remove [--global]

Options

FlagDescription
<NAME>Plugin or crate name to enable
--globalEnable for every workspace instead of just the current one, and install it for you rather than per project
--removeDrop a previously recorded enablement instead of adding one

Behavior

use is the durable, by-name form of consent. It records a use entry in the [plugins] section of the user config:

[plugins]
use = [
  "everywhere-plugin",                                    # --global
  { name = "crate-a", workspace = "/home/me/my-project" }, # default
]

Then it runs a sync, so the plugin’s skills install right away rather than waiting for the next one. A --global entry installs the plugin once for you on the agents that support it, and per project on the others; see symposium sync.

Two things a use entry can enable:

  • A dependency’s embedded plugin. Depending on a crate means compiling its code, not letting its author inject agent context, so a dependency is not a trust root — its embedded plugin stays off until you say otherwise. use is the by-name way to say so ([plugins] auto-enable is the ahead-of-time way).
  • A dormant registry plugin. A plugin whose manifest names no dependency has nothing to gate it on, so it loads dormant. A use entry naming it is what wakes it.

Anything a configured registry already offers under a depends-on gate is enabled by configuration, since pointing config at a registry is the act of trusting its curation. use-ing it is a no-op and reports as such, unless --global asks to install it for you: then the entry is recorded.

Enablement is not activation: use only adds to what may run. The plugin’s own predicates still decide when it applies.

The name must name a package before it is recorded: a registry plugin (matched exactly), a workspace dependency, or a crate on crates.io (matched the way cargo matches crate names, so widget-lib and widget_lib are the same). When a registry plugin and a crate share the name, the registry plugin wins. Otherwise the command fails with no package named <NAME> and writes nothing. Use symposium search to find the right name.

A crate the audits list revokes cannot be enabled: use fails with the revocation and its reason (for example revoked by the `symposium-audits` list: it tells the agent to fetch and run remote code) and writes nothing, since a revocation outranks every use entry. The check is made against the release that would load. A name in [plugins] disable is refused the same way.

--remove

Removes the entry in the matching scope: without --global the entry recorded for the current workspace, with it the unscoped one. A scope mismatch (or no entry at all) is an error rather than a silent success. The sync that follows reaps the plugin’s installed skills.

Example

symposium search widget      # find it
symposium use widget-skills  # enable it here
symposium status             # confirm why it is on
symposium use widget-skills --remove