Add a plugin

Goal: add one of NetScript's official plugins — workers, sagas, triggers, streams, or auth — to an existing workspace, register it with the runtime, and confirm it is wired up and healthy.

This is a task-oriented recipe. It assumes you already have a NetScript workspace (created with netscript init) and that the netscript command is on your path. Each step is a single command you run from your workspace root; the Verify step proves the plugin landed before you write a line of application code. For the exact APIs each plugin exposes, follow the reference links at the end — this guide adds the plugin; the reference documents its surface.

Before you start

You need:

• An existing NetScript workspace. If you do not have one yet, create it first with netscript init — walk through the Quickstart or the tutorials index.
• The netscript command on your path. Run netscript --help to confirm it resolves, and netscript plugin --help for the exact option spelling in your installed version. If the command is missing, install it:

deno install --global --allow-all --name netscript jsr:@netscript/cli@0.0.1-alpha.12

netscript --help
netscript plugin --help

• Aspire up if you plan to run the plugin. Adding and registering a plugin is offline, but several plugins (workers, sagas, auth) need a database and Redis to actually run. The database is Postgres by default (or mysql / mssql / sqlite, chosen at scaffold time with --db). Bring the local stack up first — cd aspire && aspire start — exactly as in Run the stack with Aspire. You do not need it up just to scaffold and register.

Step 1 — Choose the plugin kind

Each official plugin has a kind you pass to the command and a conventional installed name. Use the conventional name unless you have a specific reason to differ — generated registries, ports, and docs all assume it.

Pick the kind for the capability you need:

• workers — background job scheduling, task execution, and worker API endpoints. Fully traced through Aspire (scheduler → queue → worker → subprocess). See Background jobs.
• sagas — durable saga orchestration and long-running workflow APIs, with a selectable durable store (kv or prisma). See Durable sagas.
• triggers — trigger ingress, scheduling, and file watching over raw Hono routes. See Triggers.
• auth — an oRPC auth service (sign-in, callback, sign-out, session, me) backed by a single selectable backend (kv-oauth, WorkOS, or better-auth). See Authentication.
• streams — durable, change-data stream producers served as their own Aspire service. See Streams.

Step 2 — Add the plugin

In the public netscript CLI, plugin add takes a published plugin package specifier and dispatches to that plugin's own JSR CLI — it is not a kind-based local scaffolding command. Add an official plugin by package name:

netscript plugin add @netscript/plugin-workers

Repeat with the matching package for the other plugins: @netscript/plugin-sagas, @netscript/plugin-triggers, @netscript/plugin-auth, @netscript/plugin-streams. The only option the public add verb accepts is --project-root <path> (to target a workspace other than the current directory); it forwards any remaining arguments to the plugin's published CLI. Run netscript plugin add --help for the version-accurate surface.

The kind-based form (netscript plugin add worker --name workers with --name, --samples/--no-samples, --port, --service-refs, --plugin-refs, --db/--no-db, --force) is available only in the local contributor binary netscript-dev, not in the public netscript binary.

Useful options

Run netscript plugin add --help for the full, version-accurate list. The public netscript plugin add command takes the plugin package and forwards the verb to that plugin's own CLI; the only framework-level flag it accepts is:

Step 3 — Generate registries and wire the database

After adding plugins, regenerate the plugin registries so the runtime can discover them:

netscript generate plugins

If a plugin contributes runtime configuration schemas, also run:

netscript generate runtime-schemas

Plugins that contribute Prisma models (workers, sagas, and auth) need their tables created. With Aspire already running (cd aspire && aspire start), apply migrations and generate the client:

netscript db init --name add-plugin

netscript db generate

netscript db seed

Step 4 — Verify the plugin is registered

List the registered plugins to confirm your new plugin appears:

netscript plugin list

You should see your plugin in the inventory — for example, workers, sagas, triggers, auth, and streams if you added all five. Then run the health check:

netscript plugin doctor

plugin doctor checks installed NetScript plugin health and reports wiring problems (missing registration, port collisions, absent database tables). A clean run means the plugin is registered, wired, and ready to use.

# Detailed info for a single installed plugin
netscript plugin info @netscript/plugin-auth

# Bring the whole stack up and exercise the plugin's service
cd aspire && aspire start
# Aspire dashboard: http://localhost:18888
# auth-api:         http://localhost:8094

Manage plugins later

Once a plugin is installed you can inspect, update, and remove it without re-scaffolding:

Run netscript plugin --help for the complete, version-accurate command set.

Reference

Where to go next

• Build on the plugin you just added. Next up: Add a service to give the plugin something to call, or Configure authentication if you added the auth plugin.
• Understand the model. Read Plugin architecture for the design behind installable capabilities, ports, and runtime registration.
• Browse capabilities. The capabilities section maps each plugin to the problem it solves, with runnable examples.