Managing Plugins

Accent CMS provides CLI commands to manage plugins without editing files manually, plus development conveniences that keep a broken plugin from taking the site down.

Managing Plugins (CLI)

Scaffolding a New Plugin

accent plugin new my-plugin --lang rust   # or: --lang js

Creates a my-plugin/ directory containing a complete, buildable content-hook plugin in the chosen language, including the slice of the WIT contract it needs. The command prints the build steps for the toolchain you picked. See Writing a Plugin for the full walkthrough.

Listing Installed Plugins

accent plugin list

Displays a summary table of all installed plugins:

NAME                      VERSION    HOOKS                FILTERS    ROUTES
---------------------------------------------------------------------------
syntax-highlight          0.2.0      on_render            1          0
contact-form              1.0.0      none                 0          1

Inspecting a Plugin

accent plugin info syntax-highlight

Shows detailed metadata: name, version, API version, description, registered hooks, filters, routes, shortcodes, and configuration. An installed plugin is described entirely from disk – no network access.

A plugin that is not installed is looked up in the hub registry instead: the output says plainly that it is a registry listing, not an install, and shows the latest version, trust tier, description, published versions, and where the code lives. A name the registry does not know either gets a “did you mean” suggestion and a pointer at accent plugin search.

Installing from the Registry

# Install the latest version
accent plugin install syntax-highlight

# Install a specific version
accent plugin install syntax-highlight@0.2.0

Downloads the plugin from the configured registry, verifies the SHA-256 checksum, and places it in the plugins directory. If a plugin with the same name is already installed, you must remove it first.

Installing requires a project: in a directory with no config file, the command refuses and points at accent init – there is no project that could load the plugin, so a stray plugins/ directory would be its only effect. Pass --force to deliberately prepare a bare directory anyway.

The configured registry defaults to the Hub – the signed index of plugins, themes, and starter templates. Browse it to see what a name resolves to before you install it; hub.registry_url in config.yaml points somewhere else if you run your own. Themes install and templates scaffold through the same registry – see The Hub for all three kinds.

Installing a plugin does not switch the plugin system on. A project that leaves plugins.enabled unset – which the starter template does – loads nothing: the files are on disk and verified, but no hook runs, the plugin’s routes 404 and any island it provides never hydrates. The install says so rather than leaving you to find out:

Note: plugins are not enabled for this project, so this one will not load.
      Set `plugins.enabled: true` in config.yaml.

It is a note and not a refusal – installing into a project you intend to enable later is perfectly reasonable. See Configuration Reference for the block.

To go the other way – turning a plugin, theme, or starter template of your own into something installable – see Publishing Artifacts.

Searching the Registry

accent plugin search forms

Matches the query against plugin names, descriptions, and tags in the signed registry index, case-insensitively, and shows each match’s latest version and trust tier. Retracted (yanked) versions are never offered.

Keeping Plugins Current

# Report installed-versus-latest without changing anything
accent plugin outdated

# Update to the registry's latest version
accent plugin update accent-contact

# Or pin an exact version (up or down)
accent plugin update accent-contact@0.1.0

update runs the same verification as install – signed documents, checksum, hardened extraction – and stages the new version completely before the installed one is touched, so a failed update leaves the previous version in place and working. An unpinned update never downgrades; if your installed version was retracted by its publisher, update says so and moves you to the newest version still published. See The Hub for the full update and retraction rules shared by plugins and themes.

Removing a Plugin

accent plugin remove syntax-highlight

Deletes the plugin directory and all its contents. The plugin must be reinstalled to use it again.

Custom Config Path

All plugin commands accept --config to specify a config file (for resolving the plugins directory):

accent plugin --config prod.yaml list

Hot Reload

When dev.hot_reload is enabled, plugin WASM files are watched for changes. Modifying a .wasm file triggers an automatic reload of that plugin without restarting the server. Template filters provided by plugins are re-registered after reload.

The replacement is compiled before the running plugin is swapped out, which has two consequences worth knowing while you iterate:

  • A save that does not compile changes nothing. The error is logged and the previously loaded version of the plugin keeps handling requests, so a half-written build never leaves a gap where the plugin’s routes, filters, or shortcodes are missing.
  • Requests keep being served during the recompile. Pages that use other plugins (or none) are not blocked while your plugin is rebuilt.

Graceful Error Handling

The plugin system is designed to be resilient:

  • Missing plugins directory: The server starts normally with no plugins loaded
  • Invalid plugin.toml: The plugin is skipped with a warning; other plugins still load
  • Missing plugin.wasm: The plugin is skipped with a warning
  • WASM load failure: The plugin is skipped; the server continues
  • Failed hot reload: The previously loaded version of the plugin stays live
  • Runtime errors: Plugin errors are logged; original content is preserved

This means a broken plugin will never prevent your site from serving content.