CLI Reference

The overseer CLI is included in the @overseer-studio/sdk package. It handles authentication, plugin scaffolding, building, and publishing.

Installation#

Install the SDK as a dev dependency and wire up the CLI via npm scripts:

npm install --save-dev @overseer-studio/sdk

{
  "scripts": {
    "overseer": "overseer"
  }
}

All commands below use npm run overseer -- <command>.

Authentication#

login#

Authenticate with the marketplace. Saves your token to ~/.overseer/config.json.

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

whoami#

Display the currently authenticated user.

npm run overseer -- whoami

Scopes#

A scope is a namespace you own — for example, @yourname. Your plugin IDs use it as a prefix: @yourname/my-plugin. Claim a scope before creating plugins.

scope list#

List all scopes you have claimed.

npm run overseer -- scope list

scope claim <scope>#

Claim a new scope.

npm run overseer -- scope claim @yourname

Scope names must start with @ and use lowercase letters, numbers, and hyphens.

scope release <scope>#

Release a scope you own. The scope must have no published plugins.

npm run overseer -- scope release @yourname

Plugin commands#

init#

Scaffold a new plugin manifest in the current directory. Runs an interactive prompt to collect plugin details, then writes manifest.json and creates extensions/ and presets/ directories.

npm run overseer -- init

If you are logged in and have claimed scopes, the prompt lets you choose one. Otherwise, you can enter a plugin ID manually.

The generated manifest.json starts at version 0.1.0. Edit it freely after initialization.

build#

Pack the plugin into plugin.tar.gz and write plugin.json.

npm run overseer -- build
npm run overseer -- build --force

Output:

publish#

Build and publish the plugin to the marketplace.

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

Publishing registers the plugin with the marketplace, uploads the archive to storage, and updates plugin.json with the public package URL.

See Publishing a Plugin for the full workflow.

Environment variables#

Config file#

Authentication tokens are stored in ~/.overseer/config.json with 0600 permissions (owner read/write only). You can delete this file to log out.