nself plugin

Install, manage, and develop nSelf plugins. 26 free MIT plugins ship with the CLI. 100 paid plugins unlock with a bundle license. Build your own with Plugin SDK v2.

Quick start

# Browse available plugins
nself plugin list

# Install a free plugin
nself plugin install notify

# Install a paid plugin (requires license key)
nself plugin install ai

# Check status of all installed plugins
nself plugin status

Synopsis

nself plugin <SUBCOMMAND> [FLAGS]

Description

The nSelf plugin system is the extension layer that adds capabilities on top of the core CLI stack. Plugins are containerized services — each runs in its own Docker container managed by the nSelf orchestrator. They expose GraphQL APIs via Hasura Remote Schemas and REST endpoints via Nginx.

The 26 free plugins are MIT licensed and install without a license key. The 100 paid plugins are license-gated: set your key with nself license set, then install any plugin in your subscribed bundles. See pricing for bundle details.

Plugin SDK v2 (added in P98 S81) enables local development with hot-reload via thedev, link, unlink, test,debug, and logs subcommands. Build, test, and submit plugins without leaving the CLI.

Plugin inventory

Subcommands — Lifecycle

nself plugin list

List plugins available for installation. Shows free plugins, plugins available under your current license, and plugins from other bundles.

nself plugin list
# NAME                    BUNDLE      STATUS      VERSION
# ai                      ɳClaw       installed   2.4.1
# claw                    ɳClaw       installed   1.9.3
# notify                  free        installed   1.2.0
# chat                    ɳChat       available   3.1.0
# media-processing        ɳTV         locked      2.0.0

Show end-of-life plugins:

nself plugin list --show-eol

nself plugin install <name>

Install a plugin. Downloads the container image, registers the Remote Schema with Hasura, adds the Nginx routing rules, and starts the plugin. Running nself build is not required after installation — the install command handles it.

# Install a single plugin
nself plugin install notify

# Install multiple plugins at once
nself plugin install ai claw mux voice

# Install a specific version
nself plugin install ai@2.3.0

# Install with custom port (overrides default)
nself plugin install notify --port 3825

nself plugin remove <name>

Remove an installed plugin. Stops the container, removes the Remote Schema registration, cleans Nginx routing, and optionally purges the data volume.

nself plugin remove notify

# Purge plugin data volume (irreversible)
nself plugin remove notify --purge

nself plugin update [name]

Update a specific plugin to the latest compatible version, or update all installed plugins at once.

# Update one plugin
nself plugin update ai

# Update all installed plugins
nself plugin update

nself plugin updates

List installed plugins that have newer versions available. Does not install anything.

nself plugin updates
# NAME    INSTALLED   AVAILABLE   BREAKING
# ai      2.3.0       2.4.1       no
# claw    1.8.0       1.9.3       no

nself plugin refresh

Refresh the plugin registry cache from plugins.nself.org. Run this after a nSelf release to see newly available plugins.

nself plugin refresh

Subcommands — Runtime Control

nself plugin start <name>

Start a stopped plugin container without reinstalling.

nself plugin start notify

nself plugin stop <name>

Stop a running plugin container. The plugin remains installed and can be started again.

nself plugin stop notify

nself plugin disable <name>

Disable a plugin — stops the container and removes it from the Nginx routing and Hasura Remote Schema, but keeps the installation and data intact.

nself plugin disable notify

nself plugin enable <name>

Re-enable a disabled plugin — restores Nginx routing and the Remote Schema without reinstalling.

nself plugin enable notify

nself plugin status [name]

Show runtime status of all installed plugins, or a specific plugin.

# All plugins
nself plugin status
# NAME    STATE     PORT    UPTIME    VERSION
# ai      running   3856    2d 4h     2.4.1
# notify  running   3820    2d 4h     1.2.0
# claw    stopped   —       —         1.9.3

# Single plugin
nself plugin status ai
# Plugin:   ai
# State:    running
# Port:     3856
# Uptime:   2 days 4 hours
# Version:  2.4.1
# Remote Schema: registered (Hasura)
# Nginx route:   /plugin/ai → localhost:3856

nself plugin inventory

Full inventory of installed plugins: name, version, port, bundle, license tier, and data volume size.

nself plugin inventory --json | jq '.[] | {name, version, port}'

nself plugin info <name>

Show detailed metadata for any plugin — installed or not.

nself plugin info ai
# Name:         ai
# Bundle:       ɳClaw
# Version:      2.4.1 (latest)
# License:      paid
# Language:     Go
# Port:         3856
# Description:  AI inference routing, embedding, and model management
# Dependencies: (none)
# Env vars:     AI_PROVIDER, AI_MODEL, OPENAI_API_KEY, OLLAMA_BASE_URL
# Changelog:    https://nself.org/plugins/ai/changelog

Subcommands — Plugin SDK v2 (Development)

These subcommands are part of Plugin SDK v2, added in P98 S81. They enable a full local development workflow — write, test, and publish plugins without leaving the CLI.

nself plugin new <name>

Scaffold a new plugin from the official template. Creates a directory with the standard structure, Dockerfile, manifest, and example GraphQL schema.

nself plugin new my-plugin
# Created: ./my-plugin/
#   plugin.yaml       — manifest
#   Dockerfile
#   main.go           — entry point
#   schema.graphql    — Remote Schema definition
#   handler.go        — request handler
#   README.md

Choose a template language:

nself plugin new my-plugin --lang go     # default
nself plugin new my-plugin --lang rust
nself plugin new my-plugin --lang ts

nself plugin dev <name>

Start a plugin in development mode with hot-reload. The plugin runs inside the nSelf stack but rebuilds automatically when source files change. File-watching uses the host filesystem via a bind mount — no manual Docker build cycle.

# From inside the plugin directory
nself plugin dev my-plugin

# From any directory, specifying the path
nself plugin dev my-plugin --path ./my-plugin

# Dev mode output
# [my-plugin] Watching ./my-plugin for changes...
# [my-plugin] Build complete (0.8s)
# [my-plugin] Container started on port 3900
# [my-plugin] Remote Schema registered
# [my-plugin] → modify a .go file to trigger reload

Dev mode hot-reload cycle (Plugin SDK v2):

1. File change detected
2. Container rebuild (incremental, typically under 2s for Go)
3. Old container gracefully stopped
4. New container started on same port
5. Remote Schema re-registered if schema changed

nself plugin link <path>

Link a local plugin directory into the running nSelf stack without starting dev mode. Useful when you manage the rebuild cycle yourself (e.g. with your own watcher or Makefile).

nself plugin link ./my-plugin
# ✓ my-plugin linked from ./my-plugin
# Remote Schema registered. Port: 3900.

nself plugin unlink <name>

Remove a linked local plugin from the running stack.

nself plugin unlink my-plugin
# ✓ my-plugin unlinked. Remote Schema removed.

nself plugin test <name>

Run the plugin's test suite inside an isolated container. Tests run against a fresh database schema — no production data is touched.

nself plugin test my-plugin
# Building test container...
# Running unit tests...    ✓ 14 passed
# Running schema tests...  ✓ 6 passed
# Running integration...   ✓ 3 passed
# Coverage: 87.3%

Run only a subset of tests:

nself plugin test my-plugin --run TestHandleCreate

nself plugin debug <name>

Attach a debugger to a running plugin container. For Go plugins, this opens a Delve remote debug session. For Node plugins, it opens the V8 inspector protocol.

nself plugin debug my-plugin
# Delve listening on :2345
# Connect your IDE debugger to localhost:2345

nself plugin logs <name>

Stream logs from a running plugin container. Combines stdout and stderr.

# Follow logs
nself plugin logs my-plugin

# Last 100 lines
nself plugin logs my-plugin --tail 100

# Filter by log level
nself plugin logs my-plugin --level error

# Since a timestamp
nself plugin logs my-plugin --since 2026-05-07T10:00:00Z

nself plugin submit [path]

Submit a plugin for inclusion in the nSelf plugin registry. Runs a pre-submission validation check, then uploads the manifest and container to the registry review queue.

# From inside the plugin directory
nself plugin submit

# Validate without submitting
nself plugin submit --dry-run

Subcommands — Marketplace

nself plugin marketplace list

Browse all plugins in the marketplace, including community-contributed plugins.

nself plugin marketplace list --category ai
nself plugin marketplace list --sort downloads

nself plugin marketplace search

nself plugin marketplace search "stripe billing"
nself plugin marketplace search webhook

nself plugin marketplace info

nself plugin marketplace info my-community-plugin

Compatibility checking

nself plugin compat-check

Check compatibility of all installed plugins against the current nSelf CLI version. Run after upgrading the CLI to catch breaking changes before they surface at runtime.

nself plugin compat-check
# PLUGIN   INSTALLED   COMPAT   NOTES
# ai       2.4.1       ✓        —
# claw     1.9.3       ✗        Requires ai >= 2.4.0 (update ai first)
# notify   1.2.0       ✓        —

Flags

Environment variables

• NSELF_PLUGIN_LICENSE_KEY — license key for paid plugins (same as set by nself license set)
• NSELF_PLUGIN_REGISTRY — override the registry URL (default: https://plugins.nself.org)
• NSELF_PLUGIN_DEV_PORT_START — starting port for dev-mode plugins (default: 3900)

Examples

Install the ɳClaw bundle

nself license set nself_pro_xxxxxxxx...
nself plugin install ai claw mux voice browser google notify cron claw-budget claw-news claw-web

Build and test a plugin locally

nself plugin new my-analytics --lang go
cd my-analytics
nself plugin dev my-analytics    # hot-reload dev loop in another terminal
# ... edit main.go ...
nself plugin test my-analytics
nself plugin submit --dry-run

Update all plugins and check for breaking changes

nself plugin updates
nself plugin compat-check
nself plugin update

Stream logs from the AI plugin with error filter

nself plugin logs ai --level error --tail 50

Exit codes

• 0 — success
• 1 — generic error
• 2 — invalid arguments
• 3 — license required (paid plugin without valid key)
• 4 — plugin not found
• 5 — compatibility conflict (compat-check failed)

Related

• nself license — activate and manage plugin license keys
• nself ollama — manage the Ollama local LLM integration (used by the AI plugin)
• Plugin bundles and pricing