# 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-4--verify-the-plugin-is-registered) step proves the plugin landed before you write a line of application code. For the exact APIs each plugin exposes, follow the [reference links](#reference) at the end — this guide adds the plugin; the reference documents its surface.

> Plugins compose; they do not replace your service
>
> A plugin is an
>
> installable capability
>
> — a background-job runtime, a saga orchestrator, an auth service — that scaffolds its own workspace folder, registers itself in your runtime, and (where applicable) runs as its own Aspire service on a dedicated port. Your application service and your plugins run side by side. See
>
> Plugin architecture
>
> for the design behind the model.

## 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](https://rickylabs.github.io/netscript/quickstart/) or the [tutorials index](https://rickylabs.github.io/netscript/tutorials/).
- **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:

```bash
deno install --global --allow-all --name netscript jsr:@netscript/cli@0.0.1-beta.11
```

```bash
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, the recommended engine (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](https://rickylabs.github.io/netscript/explanation/aspire/). You do **not** need it up just to scaffold and register.

> Run commands from the workspace root
>
> Every command below runs from your workspace root. To target a different project, pass
>
> --project-root <path>
>
> — it defaults to the current directory. Run
>
> netscript plugin install --help
>
> for the version-accurate option list before you rely on any flag.

## 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.

**Official plugins**

| Kind | Conventional name | JSR package | Default port | Reference |
| --- | --- | --- | --- | --- |
| `worker` | `workers` | `@netscript/plugin-workers` | 8091 | [workers](https://rickylabs.github.io/netscript/reference/workers/) |
| `saga` | `sagas` | `@netscript/plugin-sagas` | 8092 | [sagas](https://rickylabs.github.io/netscript/reference/sagas/) |
| `trigger` | `triggers` | `@netscript/plugin-triggers` | 8093 | [triggers](https://rickylabs.github.io/netscript/reference/triggers/) |
| `auth` | `auth` | `@netscript/plugin-auth` | 8094 | [auth](https://rickylabs.github.io/netscript/capabilities/auth/) |
| `stream` | `streams` | `@netscript/plugin-streams` | 4437 | [streams](https://rickylabs.github.io/netscript/reference/streams/) |

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](https://rickylabs.github.io/netscript/capabilities/background-jobs/).
- **sagas** — durable saga orchestration and long-running workflow APIs, with a selectable durable store (`kv` or `prisma`). See [Durable sagas](https://rickylabs.github.io/netscript/capabilities/durable-sagas/).
- **triggers** — trigger ingress, scheduling, and file watching over raw Hono routes. See [Triggers](https://rickylabs.github.io/netscript/capabilities/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](https://rickylabs.github.io/netscript/capabilities/auth/).
- **streams** — durable, change-data stream producers served as their own Aspire service. See [Streams](https://rickylabs.github.io/netscript/capabilities/streams/).

> auth is a first-class official plugin
>
> Auth is now added the same way as workers, sagas, triggers, and streams — through
>
> netscript plugin install auth
>
> . It installs the
>
> @netscript/plugin-auth
>
> dependency, emits a user-owned
>
> auth/mod.ts
>
> glue barrel, registers the
>
> auth-api
>
> service on port
>
> 8094
>
> , and contributes its package-provided Prisma models. The active backend is selected at runtime with
>
> NETSCRIPT_AUTH_BACKEND
>
> (default
>
> kv-oauth
>
> ). See
>
> Configure authentication
>
> for the backend setup.

## Step 2 — Add the plugin

In the public `netscript` CLI, `plugin install` accepts either an official bare alias (`workers`, `sagas`, `triggers`, `auth`, `streams`) or a published plugin package specifier such as `@netscript/plugin-workers`. Add an official plugin by alias:

```bash
netscript plugin install workers --name workers
```

Repeat with the matching alias for the other plugins: `sagas`, `triggers`, `auth`, and `streams`. The package-spec forms also work, for example `netscript plugin install @netscript/plugin-workers --name workers` or an explicit `jsr:` specifier. Run `netscript plugin install --help` for the version-accurate surface.

### Useful options

Run `netscript plugin install --help` for the full, version-accurate list. The public `netscript plugin install` command takes the plugin alias or package specifier and applies the workspace-level install flags before invoking the plugin-owned scaffolder:

**netscript plugin install — options**

| Option | What it does |
| --- | --- |
| `--name <name>` | Plugin workspace and config key, for example `workers`. |
| `--project-root <path>` | Target a workspace other than the current directory. |
| `--port <port>` | Override the plugin service port. |
| `--db <engine>` / `--no-db` | Provision or target a database engine, or skip database wiring. |
| `--samples` / `--no-samples` | Include or skip user-owned sample stubs. |
| `--jsr-url <specifier>` / `--local-path <path>` | Use an explicit JSR package or local plugin package directory. |
| `--force` | Overwrite generated files if they already exist. |

> Contributor CLI uses local sources
>
> The local contributor command
>
> deno run -A packages/cli/bin/netscript-dev.ts plugin install <kind>
>
> accepts the same framework-level install flags, but resolves against the monorepo checkout instead of the globally installed public CLI. Always run
>
> netscript plugin install --help
>
> for the option list your installed version actually exposes.

> auth needs a database and KV
>
> The auth plugin sets
>
> requiresDb
>
> and
>
> requiresKv
>
> , and contributes its own Prisma models (
>
> auth_users
>
> ,
>
> auth_sessions
>
> ,
>
> auth_accounts
>
> ,
>
> auth_verifications
>
> ). Keep DB wiring on (do not pass
>
> --no-db
>
> ) and run the database steps in
>
> Step 3
>
> so its tables exist before the service starts.

## Step 3 — Generate registries and wire the database

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

```bash
netscript generate plugins
```

If a plugin contributes runtime configuration schemas, also run:

```bash
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:

```bash
netscript db init --name add-plugin
```

```bash
netscript db generate
```

```bash
netscript db seed
```

> Aspire is step 2, the database is step 3
>
> netscript db
>
> talks to the database that Aspire provisions — Postgres by default, or
>
> mysql
>
> /
>
> mssql
>
> /
>
> sqlite
>
> if you chose a different engine with
>
> --db
>
> at scaffold time (sqlite is file-backed, so it has no Aspire container resource). Always
>
> cd aspire && aspire start
>
> before
>
> any
>
> db
>
> command — see
>
> Run the stack with Aspire
>
> . Skip these database steps only when every plugin you added is stateless.

## Step 4 — Verify the plugin is registered

List the registered plugins to confirm your new plugin appears:

```bash
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:

```bash
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.

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

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

> Confirm in the Aspire dashboard
>
> Service-bearing plugins appear as resources in the Aspire dashboard at
>
> `https://localhost:18888`
>
> once
>
> aspire start
>
> is up. A green resource on the plugin's port (workers
>
> :8091
>
> , sagas
>
> :8092
>
> , triggers
>
> :8093
>
> , auth
>
> :8094
>
> , streams
>
> :4437
>
> ) confirms the plugin is live end to end.

## Manage plugins later

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

**Plugin lifecycle commands**

| Command | Purpose |
| --- | --- |
| `netscript plugin list` | List installed plugins in the current workspace. |
| `netscript plugin info <name>` | Show detailed metadata for one installed plugin. |
| `netscript plugin doctor` | Health-check installed plugins and report wiring problems. |
| `netscript plugin update <pkg>` | Dispatches the `update` verb to the plugin's own published CLI (e.g. `netscript plugin update @netscript/plugin-workers`). The argument is a JSR package specifier, not an installed plugin name. |
| `netscript plugin remove <name>` | Remove an installed plugin from the workspace. |

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

## Reference

[workers  Background jobs, scheduling, task execution.](https://rickylabs.github.io/netscript/netscript/reference/workers/)

[sagas  Durable saga orchestration (kv | prisma store).](https://rickylabs.github.io/netscript/netscript/reference/sagas/)

[triggers  Trigger ingress, scheduling, file watching.](https://rickylabs.github.io/netscript/netscript/reference/triggers/)

[auth  oRPC auth service with a selectable backend.](https://rickylabs.github.io/netscript/netscript/capabilities/auth/)

[streams  Durable change-data stream producers.](https://rickylabs.github.io/netscript/netscript/reference/streams/)

[All packages  Browse the full package and plugin index.](https://rickylabs.github.io/netscript/netscript/reference/)

### Where to go next

- **Build on the plugin you just added.** Next up: [Add a service](https://rickylabs.github.io/netscript/services-sdk/how-to/add-a-service/) to give the plugin something to call, or [Configure authentication](https://rickylabs.github.io/netscript/identity-access/how-to/add-authentication/) if you added the auth plugin.
- **Understand the model.** Read [Plugin architecture](https://rickylabs.github.io/netscript/explanation/plugin-system/) for the design behind installable capabilities, ports, and runtime registration.
- **Browse capabilities.** The [capabilities](https://rickylabs.github.io/netscript/capabilities/) section maps each plugin to the problem it solves, with runnable examples.