Plugin commands reference

Everything you can do with plugins from the shell lives under syntic plugin. Inside a session, /plugin and /reload-plugins cover the same ground interactively. This page lists every subcommand, argument and flag, plus the launch flags that bring in a plugin just for the current run.

Plugins are referred to as <plugin>@<marketplace>, for example formatter@acme. Names are case-sensitive.

Global flag

Flag	Effect
`--json`	Accepted by every `syntic plugin` subcommand. `list`, `details` and `marketplace list` print their own records. Every other subcommand prints `{"ok": true, "code": 0, "messages": [...]}`, or `{"ok": false, "code": 1, "error": "..."}` on failure.

Exit codes: 0 on success, 1 on any failure (including “not installed” and policy refusals), 2 for an unrecognised on/off value.

Install and manage

`syntic plugin install <plugin@marketplace>`

Installs a plugin from a saved catalog.

syntic plugin install formatter@acme
syntic plugin install release-helper@acme --scope project -y --config registry=https://registry.example.com
syntic plugin install formatter@acme --marketplace acme/acme-plugins

Flag	Effect
`--scope <user\|project\|local>`	Scope recorded for the install. Default `user` (`global` is accepted as another spelling). `managed` cannot be chosen here.
`-y`, `--yes`	Install missing dependencies without asking.
`--config <KEY=VALUE>`	Set one of the plugin’s options. Repeatable.
`--marketplace <SOURCE>`	If the catalog is not saved yet, add it from this source first.

Before installing, the catalog is refreshed so the newest listing is used. If the catalog is not saved, install adds it from --marketplace, or from a catalog of that name in your settings (extraKnownMarketplaces). Missing dependencies are offered for install (on a terminal you are asked; with -y they are installed). The output names any required options that are still unset, and ends with your organization’s install note if policy sets one.

`syntic plugin uninstall <plugin@marketplace>`

Removes the plugin and its files. If other enabled plugins depend on it, the output names them; they stay off until it returns. Plugins that were installed only as its dependencies, and that nothing needs any more, are removed too.

`syntic plugin enable <plugin@marketplace>`

Turns an installed plugin on. Its disabled dependencies are turned on with it. Refused when managed policy force-disables the plugin.

`syntic plugin disable <plugin@marketplace>`

Turns an installed plugin off without removing it. Names any enabled plugins that depend on it.

`syntic plugin disable-all`

Turns every installed plugin off and reports how many were on.

`syntic plugin update <plugin@marketplace>`

Fetches the plugin again from its catalog and records the new version. Its on/off state and scope are kept. Prints “already up to date” or the old and new versions. A failed fetch leaves the old copy in place.

`syntic plugin configure <plugin@marketplace> [KEY=VALUE ...]`

Sets the plugin’s options (userConfig in its manifest). With no pairs, asks for each option on the terminal. Plain values are saved under ~/.syntic/plugins/.options/; options marked sensitive go to your system’s credential store.

`syntic plugin list`

Lists installed plugins with version and [enabled] or [disabled].

Flag	Effect
`--available`	List plugins your saved catalogs offer that are not installed, with descriptions.

With --json, installed plugins are printed as an array of objects with id, name, marketplace, version, enabled and scope. With --available --json: id, name, marketplace, description.

`syntic plugin details <plugin>`

Accepts plugin or plugin@marketplace. Lists what an installed plugin brings: skills, commands, agents, hooks, MCP servers and language servers, plus an estimate of how many tokens its listing adds to every request. With --json: id, skills, commands, agents, hooks, mcpServers, lspServers, listingTokens. See Measure a plugin.

`syntic plugin prune`

Removes plugins that were installed only as another plugin’s dependency and that nothing needs now.

`syntic plugin reconcile`

Lists installed plugins whose catalog is no longer saved.

Flag	Effect
`--prune`	Remove those plugins. Plugins in the `managed` scope are reported but left in place.

Build and release

`syntic plugin init <name>`

Scaffolds a plugin in .syntic/skills/<name>/ of the current folder: a .syntic-plugin/plugin.json (version 0.1.0) and a first SKILL.md. The name may use letters, digits, ., _ and -. Never overwrites an existing folder. The plugin loads at the next start or /reload-plugins.

Flag	Effect
`--description <TEXT>`	One-line description for the manifest and the skill.

See Create a plugin.

`syntic plugin validate <path>`

Checks a manifest without installing anything. path is the file, or a folder holding .syntic-plugin/plugin.json or plugin.json. Prints each problem as error or warning with the field it concerns, then a valid or invalid verdict. Exits 1 on any error.

Flag	Effect
`--marketplace`	Treat the file as a `marketplace.json` (a folder is searched for `.syntic-plugin/marketplace.json`, then `marketplace.json`).

`syntic plugin eval <path>`

Also available as syntic plugin test. Runs a plugin’s eval suite: path is the plugin folder (the suite is evals/evals.json) or the suite file itself. Each case runs as a one-shot session with the plugin loaded, and its answer is scored. Writes report.json and report.html and exits non-zero when a case fails.

Flag	Effect
`--out <DIR>`	Where to write the reports. Default `<plugin>/evals/results`.

See Test a plugin.

`syntic plugin tag [path]`

Creates the annotated git tag <name>--v<version> from the manifest of the plugin in path (default: the current folder). Tags locally only; the output shows the git push to run.

Flag	Effect
`--dry-run`	Print the tag that would be created.

See Release a plugin.

Marketplaces

`syntic plugin marketplace add <source>`

Saves a catalog and reads its listing. The catalog is saved under the name it declares. Accepted sources:

Form	Example
GitHub `owner/repo`, optional `@ref` or `#ref`	`acme/acme-plugins@stable`
Git URL (https ending in `.git`, `ssh://`, `git://`, `git+https://`, `user@host:path`)	`git@git.example.com:team/plugins.git`
A GitHub web URL	`https://github.com/acme/acme-plugins`
GitLab project	`gitlab:group/project#v2`
Local folder or file (`./`, `../`, `/`, `~`, a drive letter, or `file://`)	`~/src/acme-plugins`
Any other https URL, serving the JSON	`https://plugins.example.com/marketplace.json`
npm package	`npm:@acme/plugins` or `@acme/plugins`

Refused when managed policy blocks the source, or when it needs git and git is missing.

`syntic plugin marketplace list`

Lists saved catalogs with their plugin counts, marking ones whose auto-update is off. With --json: name, source, plugins, pluginCount, note, autoUpdate.

`syntic plugin marketplace remove <name>`

Forgets a catalog. Plugins installed from it stay installed; use syntic plugin reconcile --prune to remove them.

`syntic plugin marketplace refresh [name]`

Fetches catalog listings again. With a name, refreshes that one even if its auto-update is off. Without a name, refreshes every saved catalog. Each catalog is reported separately (refreshed (N plugins, +2), skipped, or refresh failed), and one failure does not stop the others. If a catalog now declares a new name, it is saved under that name and its installed plugins follow. Installed plugins the catalog no longer lists are flagged.

Flag	Effect
`--auto-only`	With no name, refresh only catalogs whose auto-update is on.

`syntic plugin marketplace auto-update <name> <on|off>`

Turns a catalog’s background refresh on or off. Also accepts true/false, yes/no, 1/0, enable/disable. New catalogs start with it on.

In a session

`/plugin`

Opens the plugin manager (also /plugins). Tab or the arrow keys switch between three tabs. Esc or q closes it.

Tab	Keys
Installed	`Enter` shows what a plugin contains. `Space` turns it on or off. `r` updates it. `u` removes it. `f` cycles between all, enabled only and disabled only. `/` searches by name and description.
Discover	Plugins your catalogs offer that are not installed. `Enter` or `i` installs for you; `p` installs with project scope. `/` searches.
Marketplaces	`a` adds a catalog (type its source, then `Enter`). `u` refreshes the selected one. `x` twice removes it. `r` re-reads catalogs named in your settings.

In the details view of a plugin, Space toggles it, r updates it, u removes it and Esc goes back. When the manager opens, catalogs named in settings (extraKnownMarketplaces) are added if they are not saved yet. Installs and toggles take effect after /reload-plugins or at the next start.

`/reload-plugins`

Scans plugins again without restarting and reports what was added and removed: commands, skills, agents and hooks. Use it after installing, enabling, disabling or editing a plugin.

Flags that load plugins for one run

These are flags on syntic itself, not on syntic plugin.

Flag	Effect
`--plugin-dir <PATH>`	Use a plugin from a folder or `.zip` for this session only, without installing it. A folder of plugins loads each one inside. Repeatable.
`--plugin-url <URL>`	Download a plugin `.zip` for this session only. Only `https://` is fetched (plain `http://` is allowed for `localhost`). A failed download falls back to the last good copy. Repeatable.
`--plugin <NAME@MARKETPLACE>`	Install a plugin before the run without prompting, then continue. Meant for scripted and `--print` runs. The catalog must already be saved. Results are printed to standard error. Repeatable.
`--plugin-scope <SCOPE>`	Scope for `--plugin` installs. Default `user`.
`--bare`	Skip installed and pre-seeded plugins. `--plugin-dir` folders still load.
`--safe-mode`	Turn plugins off, along with instruction files, skills, hooks and MCP servers, for troubleshooting.

A --plugin-dir or --plugin-url plugin whose name matches an installed plugin is skipped; the installed copy wins. Disable or uninstall the installed one while you test.

Environment variables

Variable	Effect
`SYNTIC_PLUGIN_GIT_PROTOCOL`	`ssh` clones GitHub `owner/repo` sources over SSH.
`SYNTIC_PLUGIN_AUTO_UPDATE`	`0`/`off` stops the daily catalog refresh; `1`/`on`/`force` refreshes every catalog at every start.
`SYNTIC_PLUGIN_SEED_DIR`	Folders of plugins that load in every session without being installed.
`SYNTIC_PLUGIN_DIRS`	Set by `--plugin-dir`; passes session plugin folders to child processes.
`SYNTIC_PLUGIN_LOCKDOWN`	`1` loads only plugins on the trust list.
`SYNTIC_TRUSTED_PLUGINS`	Comma-separated plugin or catalog names to add to the trust list.
`SYNTIC_SKILLS_PLUGIN_ONLY`	Offer only skills that come from plugins.