plugin.json Reference

Top-level fields

Nebo validates marketplace installs: the slug rules, a semantic version, at least one platform, a binaryName with no path separators or .., a login command unless auth.type is env, non-empty event names and commands, and binding templates that parse. Plugins in the user plugins directory skip validation.

Platforms

Keys are darwin-arm64, darwin-amd64, linux-arm64, linux-amd64, windows-arm64 and windows-amd64. Each entry has all five fields below. When you publish, the marketplace writes the real hash, size, signature and download URL, so leave them empty in the file you upload.

"platforms": {
  "darwin-arm64":  { "binaryName": "notes-sync",     "sha256": "", "signature": "", "size": 0, "downloadUrl": "" },
  "linux-amd64":   { "binaryName": "notes-sync",     "sha256": "", "signature": "", "size": 0, "downloadUrl": "" },
  "windows-amd64": { "binaryName": "notes-sync.exe", "sha256": "", "signature": "", "size": 0, "downloadUrl": "" }
}

Auth

Nebo reads the first of authenticated, isAuthenticated, logged_in, loggedIn or token_valid in the status output. A non-empty token_error, or the value none in credential_source, auth_method, storage or status, means signed out. The status command has 45 seconds.

{"authenticated": true, "account": "finance@example.com"}

configSchema

capabilities.configSchema describes the values an owner sets for the plugin. Each value reaches the binary as an environment variable named by key. For credential keys also listed in auth.env, the schema labels the fields of the per-employee connect form.

permissions

events

An event is a long-running watcher. Nebo starts it when an employee's workflow watches it, and restarts it if it exits. Each line the watcher writes to stdout is one event. The event name is prefixed with the slug at run time, so note.created becomes notes-sync.note.created.

"events": [
  {
    "name": "note.created",
    "description": "A note was created in the watched notebook.",
    "command": "watch --notebook {{notebook}} --format ndjson"
  }
]

Workflows subscribe to events with a watch trigger. See Triggers.

interfaceBindings

A binding maps an interface operation to one of your commands. Each binding becomes a typed tool for employees, named after the operation in lowercase with dots and hyphens as underscores: notes.search becomes notes_search. Bindings are how a plugin satisfies the capabilities an employee requires; see Capabilities.

"interfaceBindings": {
  "notes.search": "notes search --query {query} {tag[]:--tag} {limit?:--limit}",
  "invoice.create": "invoices create --amount {amount_cents:cents->dollars}"
}

Input fields a template does not name are appended as --field value. List and optional placeholders must be whole words. An operation that requires approval cannot be reached by calling the same command through plugin__<slug>.

Hooks, slash commands and routes

"capabilities": {
  "hooks": [
    { "hook": "tool.post_execute", "hookType": "filter", "command": "hook redact", "priority": 50, "timeoutMs": 500 }
  ],
  "commands": [
    { "name": "notes", "description": "Show today's notes", "command": "notes today", "slash": true }
  ],
  "routes": [
    { "path": "/callback", "method": "GET", "command": "http callback" }
  ]
}

hooks

A hook runs your command at a point in an employee's turn. Nebo writes a JSON payload to stdin. An action hook's output is ignored. A filter hook returns {"payload": ..., "handled": false}; "handled": true stops later hooks. Errors and timeouts keep the previous payload and never block the turn. After three failures in a row a hook is paused for five minutes.

commands

With "slash": true, typing /name args in chat runs command args directly, without the employee. The output is the reply. The time limit is 30 seconds.

routes

A route answers HTTP requests at /api/v1/plugins/<slug>/api/<path> on the bot, matched by path and method. The request body goes to stdin and your stdout is the response. The time limit is 30 seconds.

providers

A provider adds a chat model source. Declare id, displayName, providerType, modelsCommand and chatCommand. Nebo sends a chat request as JSON on stdin to chatCommand and reads streamed events as newline-delimited JSON on stdout, for up to 300 seconds. Only chat streaming is used today.

channel

A channel bridges a messaging service. Nebo keeps command running, reads inbound messages from its stdout and writes replies to its stdin, both as newline-delimited JSON.

setup

A setup wizard walks the owner through steps that a single form cannot cover. Values from form steps fill {{key}} in later generate arguments. Values from credentials steps are saved as the plugin's environment variables.

"setup": {
  "title": "Connect Example Chat",
  "steps": [
    { "kind": "form", "title": "Bot name", "fields": [ { "key": "bot_name", "label": "Name", "required": true } ] },
    { "kind": "generate", "title": "App manifest", "command": "manifest", "args": ["--name", "{{bot_name}}"], "outputFormat": "yaml" },
    { "kind": "external", "title": "Create the app", "url": "https://example.com/apps", "urlLabel": "Open admin" },
    { "kind": "credentials", "title": "Paste the token", "fields": [ { "key": "EXAMPLE_CHAT_TOKEN", "label": "Token", "inputType": "password", "required": true } ], "verifyCommand": "auth status" }
  ]
}

Fields have key, label, default, placeholder, maxLength, help, inputType (text, textarea, password) and required.