Publishing a Plugin

Publishing makes your plugin available in the Overseer marketplace so other users can discover and install it. Publishing is optional — plugins work locally without it.

Prerequisites#

• The @overseer-studio/sdk installed and wired up in your package.json scripts
• A plugin initialized with npm run overseer -- init
• An Overseer account and API token

Step 1: Log in#

npm run overseer -- login

You’ll be prompted for your API token. The token is saved to ~/.overseer/config.json so you only need to do this once per machine.

Step 2: Claim a scope#

A scope is a namespace prefix for your plugin IDs (e.g., @yourname). You need to claim one before you can publish.

npm run overseer -- scope claim @yourname

Scope names must be lowercase and may contain letters, numbers, and hyphens. Once claimed, the scope is yours — no one else can publish plugins under it.

Step 3: Build#

npm run overseer -- build

This packs your plugin assets into plugin.tar.gz and writes plugin.json with the build hash and asset list. The build is skipped if no source files have changed since the last build — use --force to override.

Step 4: Publish#

npm run overseer -- publish

The publish command:

1. Builds the plugin (unless --skip-build is passed)
2. Registers the plugin version with the marketplace
3. Uploads plugin.tar.gz to storage
4. Finalizes the version and updates plugin.json with the public package URL

When it finishes, you’ll see the URL where your plugin is hosted.

Publishing a new version#

Update the version field in your manifest.json (use semantic versioning: 1.0.0, 1.1.0, 2.0.0, etc.), then run:

npm run overseer -- publish

Each publish call creates a new version. Existing installations are not automatically updated — users install specific versions.

Skipping the build step#

If you’ve already run npm run overseer -- build and haven’t changed any files:

npm run overseer -- publish --skip-build

This uploads the existing plugin.tar.gz without rebuilding.

Using a token inline#

To authenticate without a saved config (useful in CI):

npm run overseer -- publish --token <your-token>

Or set the OVERSEER_TOKEN environment variable.