Install and manage plugins

Plugins reach you through marketplaces. You save a marketplace once, then install any plugin it lists by its id, plugin@marketplace. This page covers the whole loop: adding a marketplace, installing, turning plugins on and off, setting their options, updating them and removing them.

You can do all of it two ways:

In a session, with the /plugin manager (also opened by /plugins).
From your shell, with syntic plugin .... Every subcommand is listed in the plugin commands reference.

Both use the same code and the same files under ~/.syntic/plugins/, so you can mix them freely.

Save a marketplace

A marketplace is a catalog file (marketplace.json) naming each plugin it offers and the place to download it from. Save one with its source:

syntic plugin marketplace add acme/syntic-plugins          # a GitHub repository
syntic plugin marketplace add https://git.example.com/tools/plugins.git
syntic plugin marketplace add ~/src/team-plugins           # a folder on disk

The marketplace is saved under the name its marketplace.json declares, not the name of the repository. syntic plugin marketplace list shows what you have saved and how many plugins each one lists.

In /plugin, open the Marketplaces tab, press a, type the source and press Enter.

See Create a marketplace for the source forms you can use, and Host a marketplace for private repositories.

Add and install in one step

If you know the plugin and its marketplace source, --marketplace saves the marketplace for you when it is missing:

syntic plugin install formatter@acme --marketplace acme/syntic-plugins

The command fails with a clear message if the catalog at that source is not actually named acme.

Marketplaces your project suggests

A repository can name marketplaces in its .syntic/settings.json under extraKnownMarketplaces. When you open /plugin, or install a plugin from one of those marketplaces by name, Syntic Code adds it for you. Project settings only count in a folder you trust. The Plugins for your organization page shows the format.

Install a plugin

syntic plugin install formatter@acme

Before installing, the CLI pulls the marketplace’s latest listing so you get the newest version. If that refresh fails, it says so and uses the listing it already has. Then it fetches the plugin, checks that its manifest loads, records it in installed.json and prints the result:

Installed `formatter@acme` (v1.4.0) — enabled [user].

In /plugin, go to the Discover tab, pick a plugin and press Enter (or i). Press p instead to record the install with project scope.

Choose a scope

`--scope`	Meaning
`user` (default; `global` also works)	Your own install, for every project.
`project`	An install you made for the repository you are working in.
`local`	A one-off install for this checkout.

The scope is saved next to the install in installed.json and appears in syntic plugin list --json. Every enabled installed plugin loads in every session; use enable and disable to choose what is active.

Options and dependencies at install time

Flag	Effect
`--config KEY=VALUE`	Sets one of the plugin’s options right away. Repeat for more.
`-y`, `--yes`	Installs any plugins this one depends on without asking.
`--marketplace <source>`	Adds the marketplace first if it is not saved.

If a plugin declares dependencies that you do not have, the CLI asks once on the terminal: `app@acme` needs base@acme. Install it too? [Y/n]. Without a terminal the answer is no, so scripts should pass --yes. A plugin whose dependencies are missing is installed but stays off until they arrive. Read Dependencies for the full rules.

If the plugin has required options with no value yet, the install output names them so you can run syntic plugin configure.

Plugins that ship switched off

A plugin whose manifest says "defaultEnabled": false installs disabled. The output tells you: off by default; turn it on with syntic plugin enable.

Manage installed plugins

Turn plugins on and off

syntic plugin disable formatter@acme
syntic plugin enable formatter@acme
syntic plugin disable-all

Enabling a plugin also switches on any installed dependencies it needs that are off. Disabling or uninstalling a plugin that others depend on prints a “required by” note, because those plugins will stay off while it is gone.

In /plugin, the Installed tab does the same: Space turns the selected plugin on or off, and f cycles the list between all, enabled only and disabled only. / searches by name and description.

See what a plugin adds

syntic plugin details formatter@acme

formatter@acme
  Skills (2): format-file, format-diff
  Commands (1): /fmt
  Agents (0): none
  Hooks: yes
  MCP servers: none
  Language servers: none
  Adds about 64 tokens to every request (skill and command list)

You can pass just the plugin name if only one installed plugin has it. In /plugin, press Enter on a plugin to see the same breakdown. Measure a plugin explains the token figure.

Set a plugin’s options

Some plugins ask for settings, such as an API address or a token. Set them with:

syntic plugin configure release-helper@acme registry=https://registry.example.com
syntic plugin configure release-helper@acme        # asks for each option in turn

Values are checked against the types the plugin declares. Plain values are saved in ~/.syntic/plugins/.options/<id>.json (readable only by you). Options marked sensitive go to your system’s credential store instead and are shown as ••••.

Uninstall

syntic plugin uninstall formatter@acme

This removes the plugin’s files and its entry. Plugins that were installed only as its dependencies, and that nothing else needs, are removed too. Its private data folder (~/.syntic/plugins/data/<id>/) is left in place. In /plugin, press u on the Installed tab.

To clean up leftover dependencies at any time, run syntic plugin prune.

Keep plugins updated

syntic plugin update formatter@acme

This fetches the plugin again and records the new version, keeping its on/off state. You see either Updated formatter@acme: v1.4.0 → v1.5.0. or already up to date. In /plugin, press r on the Installed tab.

Marketplace refresh

Marketplace listings are what tell you a new version exists. Refresh them by hand with:

syntic plugin marketplace refresh          # every saved marketplace
syntic plugin marketplace refresh acme     # one marketplace

Once a day, an interactive session also refreshes marketplaces in the background. It never delays startup. To pin a marketplace so the background refresh skips it:

syntic plugin marketplace auto-update acme off

The SYNTIC_PLUGIN_AUTO_UPDATE environment variable overrides this: 0 or off never refreshes in the background, and 1 or on refreshes every marketplace, pinned ones included, at every start.

Background refresh updates the listings only. Installed plugins change when you run update.

When changes take effect

A running session watches installed.json and the manifests and hook files of loaded plugins. When one changes, it reloads plugins on its own within a couple of seconds. You can also run /reload-plugins to do it now. The reload reports what was added and removed.

Commands, skills, agents, output styles and hooks switch over in place. MCP servers from plugins are connected at startup, so the reload tells you to restart syntic when they change.

Use plugins in scripts

For headless runs, --plugin installs plugins before the session starts, with no prompts:

syntic -p --plugin formatter@acme --plugin-scope project "Format the changed files"

The marketplace must already be saved. Results go to standard error so they never mix with the answer. To try a plugin without installing it, see How plugins load.

Plugin safety: what a plugin can do and how to vet it.
Troubleshooting: when a plugin does not show up or will not install.
Plugin commands: every subcommand and flag.

Overview Code intelligence