Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bolt-builder/bolt-cli/llms.txt

Use this file to discover all available pages before exploring further.

Plugins let you extend Bolt beyond its built-in capabilities. A plugin is a Node or Bun module that exports a Bolt plugin manifest; when loaded, it can register new LLM providers, custom authentication methods, additional tools, and workspace adapters. Plugins can be installed for a single project or applied globally across all of your work.

​
Installing a plugin

Use bolt plugin install (alias: bolt plug) to install a plugin from npm and automatically register it in your config: 
bolt plugin install <module>

​
Flags

FlagAliasDescription
--global-gInstall into the global config instead of the current project
--force-fReplace an existing entry for the same module

​
Scope: project vs. global

By default, bolt plugin install adds the plugin to the project-level .bolt/bolt.jsonc. Pass --global to add it to your user-wide config so it loads in every project. 
# Project-scoped (default)
bolt plugin install @acme/bolt-plugin-jira

# Global — loads in every project
bolt plugin install @acme/bolt-plugin-jira --global
Run bolt --pure (or set OPENCODE_PURE=1) to start Bolt with all external plugins disabled. This is useful for debugging whether a plugin is causing unexpected behaviour, without uninstalling it.

​
Installing a published plugin

1

Find the plugin package

Search npm for packages with bolt-plugin or opencode-plugin in the name, or follow a link from a provider’s documentation.
2

Install into your project

bolt plugin install @acme/bolt-plugin-jira
Bolt installs the package, reads its manifest to detect server and TUI targets, then writes the entry to .bolt/bolt.jsonc.
3

Verify the config

Open .bolt/bolt.jsonc and confirm the plugin entry was added:
{
  "plugin": [
    "@acme/bolt-plugin-jira"
  ]
}
4

Start a session

bolt
Bolt loads the plugin at startup. Any providers or tools it registers are immediately available.

​
Manual plugin configuration

You can register plugins by editing .bolt/bolt.jsonc directly. This is useful for local plugins under development: 
{
  "plugin": [
    "./plugins/my-plugin.ts"
  ]
}
Relative paths are resolved from the project root. Both TypeScript and JavaScript entry points are supported.

​
Building a plugin

Plugins are authored against the @opencode-ai/plugin package, which provides the Hooks interface your module must satisfy. 
npm install --save-dev @opencode-ai/plugin
A minimal plugin exports a function that receives a PluginInput object and returns a Hooks object: 
import type { Plugin } from "@opencode-ai/plugin"

const myPlugin: Plugin = async (input) => {
  return {
    // auth hook — register custom authentication methods
    auth: {
      methods: [
        {
          id: "my-provider-auth",
          name: "My Provider",
          // ... provider-specific fields
        },
      ],
    },
  }
}

export default myPlugin

​
Available hook types

HookPurpose
authRegister custom authentication providers with a methods array
eventReact to session events (messages, tool calls, completions)
configRespond to configuration changes at runtime
disposeClean up resources when the plugin is unloaded
The PluginInput object exposes the client (a typed Bolt API client), project, worktree, directory, and serverUrl so your plugin can interact with the running server.

​
Environment variables

VariableDescription
OPENCODE_PURESet to 1 to run without any external plugins

Build docs developers (and LLMs) love

Get started for freeTalk to us