apus plugins

Manage Gateway plugins, hook packs, and compatible bundles.

plugins enable and plugins disable accept case-insensitive plugin IDs, including when the Gateway is stopped. Reported IDs retain their manifest spelling; plugin policy keys in config use the canonical lowercase form. The same policy applies to live activation and the next Gateway start. Runtime IDs and Gateway method names retain the plugin's declared spelling.

Plugin system

End-user guide for installing, enabling, and troubleshooting plugins.

Manage plugins

Quick examples for install, list, update, uninstall, and publishing.

Plugin bundles

Bundle compatibility model.

Plugin manifest

Manifest fields and config schema.

Security

Security hardening for plugin installs.

Commands

apus plugins list [--enabled] [--verbose] [--json]
apus plugins search <query> [--limit <n>] [--json]
apus plugins install <path-or-spec> [--link] [--force] [--pin] [--no-enable] [--accept-capabilities] [--acknowledge-install-policy-warning] [--marketplace <source>]
apus plugins inspect <id> [--runtime] [--json]
apus plugins inspect --all [--runtime] [--json]
apus plugins info <id>                    # alias for inspect
apus plugins enable <ids...> [--accept-capabilities]
apus plugins disable <ids...>
apus plugins reload <ids...> [--wait] [--accept-capabilities] [--json]
apus plugins uninstall <ids...> [--dry-run] [--keep-files] [--force]
apus plugins update <ids-or-npm-specs...> | --all [--dry-run]
apus plugins registry [--refresh] [--json]
apus plugins doctor [--json]
apus plugins init <id> [--name <name>] [--type tool|provider|feature] [--directory <path>]
apus plugins build [--root <path>] [--entry <path>] [--check]
apus plugins validate [--root <path>] [--entry <path>] [--json]
apus plugins pack [--root <path>] [--out <file.tgz>] [--json]
apus plugins marketplace entries [--offline] [--feed-profile <name>] [--json]
apus plugins marketplace list <source> [--json]
apus plugins marketplace refresh [--feed-profile <name>] [--expected-sha256 <sha256>] [--json]

For slow install, inspect, uninstall, or registry-refresh investigation, run the command with APUS_PLUGIN_LIFECYCLE_TRACE=1. The trace writes phase timings to stderr and keeps JSON output parseable. See Debugging.

In Nix mode (APUS_NIX_MODE=1), apus.json is immutable. install, update, uninstall, enable, and disable all refuse to run. Manage those choices in the Nix source for this install (programs.apus.config or instances.<name>.config for nix-apus), then rebuild. Reload remains available when no new capability consent needs to be recorded; it preserves config and installation state. See the agent-first Quick Start.

Bundled plugins ship with Apus. A little over half are enabled by default — mostly model and speech providers, plus a few others such as the bundled browser plugin. Other bundled plugins need explicit enablement or relevant configuration. Enabled does not mean currently in use. Provider use depends on configuration and requests. Providers that require authentication need credentials; keyless providers such as Microsoft speech do not. An enabled entry in plugins list does not mean the plugin is doing work.

Native Apus plugins ship apus.plugin.json with an inline JSON Schema (configSchema, even if empty). Compatible bundles use their own bundle manifests instead.

plugins list shows Format: apus or Format: bundle. Verbose list/info output also shows the bundle subtype (agent (Agent Plugins), codex, claude, or cursor) plus detected bundle capabilities.

Plugins pages

This page is an index. apus plugins is documented on six pages, one per reader job. Open the page that matches your task.

Page Read it when
Author plugins You are scaffolding, building, validating, or packing a plugin project.
Install plugins You are installing from ClawHub, npm, git, a path, an archive, or a marketplace.
List installed plugins You want the installed inventory, discovery diagnostics, or the plugin index.
Uninstall and update plugins You are removing or reloading a plugin, or updating its version and source.
Inspect and diagnose plugins You need plugin identity, runtime registrations, load errors, or registry state.
Marketplace feeds You are browsing, listing, or refreshing a marketplace or hosted signed feed.

Where each section moved

Every section anchor from the previous single-page version keeps its id here, so an existing link such as /cli/plugins#registry still resolves. Each entry points at the page that now holds the content.

Related