CLI reference

A curated, task-grouped tour of the netscript commands you reach for daily. It is the human companion to the generated /reference/cli/, which lists every command, subcommand, and flag verbatim from the published surface. When you need the exhaustive option spelling, go there — this page covers the common path and the order things happen in.

Install

The CLI is published to JSR as @netscript/cli. Install it globally for a tidy netscript command on your PATH, or run it ad-hoc with no install at all.

# Installs a `netscript` command on your PATH
deno install --global --allow-all --name netscript jsr:@netscript/cli@0.0.1-alpha.12

netscript --help

# Run the same CLI without installing anything
deno x jsr:@netscript/cli@0.0.1-alpha.12 --help

# Re-run the install with --force to pull the latest published version
deno install --global --allow-all --force --name netscript jsr:@netscript/cli@0.0.1-alpha.12

The everyday flow

Most sessions follow the same shape: scaffold a workspace, bring up Aspire, run the database workflow, then iterate. The commands below are grouped to mirror that order — and the order matters: Aspire (step 2) must be up before any db command (step 3).

1 · Scaffold

netscript init lays down the whole workspace — contracts, an example service, plugins, and the Aspire layer.

2 · Orchestrate

cd aspire && aspire start brings up your database (Postgres by default; or mysql/mssql/sqlite via --db) and Redis, and opens the dashboard at :18888. Do this before any db command.

3 · Database

netscript db init / generate / seed / status — only after Aspire is up.

4 · Extend & generate

netscript plugin add, then netscript generate plugins to wire the registry.

Scaffold & project

netscript init is the one command that creates a complete workspace: shared oRPC contracts, an optional example service, a Fresh frontend, the plugin registry, and the Aspire orchestration files. The flags below match the verified scaffold run.

Scaffold a workspace
Name	Type	Description
`netscript init`	`netscript init my-app`	Create a NetScript workspace in `my-app/` — contracts, plugin registry, Fresh app, a default Redis cache, and the Aspire layer. On a terminal it prompts for anything you omit (name, database, service, cache); add `--dry-run` to preview every file without writing.
`init (full happy path)`	`netscript init my-app --db postgres --service --service-name users --service-port 3001 --yes`	The fully-specified, non-interactive form (`--yes`): Postgres database support (swap `--db postgres` for `mysql`, `mssql`, or `sqlite`), an example oRPC `users` service on port 3001, and the default Redis cache resource.
`init --cache / --cache-backend`	`netscript init my-app --cache-backend garnet`	The shared cache is on by default with the `redis` backend. Pick another with `--cache-backend`: `redis` (default) or `garnet` are provisioned as Aspire container resources; `deno-kv` is app-level and needs no container. Pass `--cache=false` to scaffold without a cache.
`init --no-aspire`	`netscript init my-app --no-aspire`	Scaffold without the .NET Aspire footprint. You start the Fresh app directly with `deno task --cwd apps/dashboard dev` and lose the dashboard + multi-resource wiring.
`init --path / --editor`	`netscript init my-app --path ./apps --editor zed`	Place the project under a different directory and emit editor settings (`none` \| `zed` \| `vscode`).

Plugins

Plugins add capabilities — background workers, durable sagas, webhook triggers, durable streams, and authentication. Each one lands as a canonical install under plugins/<name>/ and registers its contributions; the host application never changes. After adding plugins, regenerate the registry so the project picks them up.

Public plugin package dispatch (netscript)
Name	Type	Description
`netscript plugin add`	`netscript plugin add [args...] [--project-root ]`	Run a plugin package's published add command and forward remaining arguments to that package. The public `netscript` add verb itself accepts only `--project-root`; package-specific flags belong to the plugin package CLI.
`netscript plugin add workers`	`netscript plugin add @netscript/plugin-workers`	Dispatch to the published workers plugin package. Use the package's own help for any forwarded arguments supported by that published plugin CLI.
`netscript plugin add auth`	`netscript plugin add @netscript/plugin-auth`	Dispatch to the published auth plugin package — the `auth-api` oRPC service on port 8094 exposing `/api/v1/auth/{signin,callback,signout,session,me}`. Pulls in `auth.prisma` and a single active backend selected by `NETSCRIPT_AUTH_BACKEND` (default `kv-oauth`). See add authentication.
`netscript plugin list`	`netscript plugin list`	List the plugins registered in the current workspace.
`netscript plugin doctor`	`netscript plugin doctor`	Check the health of installed NetScript plugins — a fast wiring sanity check.
`netscript plugin info`	`netscript plugin info workers`	Run a plugin's published info command for details about a single plugin.
`netscript plugin remove`	`netscript plugin remove workers`	Remove a configured plugin and update workspace registration.

Local contributor plugin scaffolding (netscript-dev)
Name	Type	Description
`plugin add worker`	`deno run -A packages/cli/bin/netscript-dev.ts plugin add worker --name workers --samples`	Local-source contributor path for first-party worker samples. The kind-based command is not part of the public `netscript` package-dispatch surface.
`plugin add saga`	`deno run -A packages/cli/bin/netscript-dev.ts plugin add saga --name sagas --samples`	Local-source contributor path for sagas samples.
`plugin add trigger`	`deno run -A packages/cli/bin/netscript-dev.ts plugin add trigger --name triggers --samples`	Local-source contributor path for triggers samples.
`plugin add stream`	`deno run -A packages/cli/bin/netscript-dev.ts plugin add stream --name streams --samples`	Local-source contributor path for streams samples.
`plugin add options`	`--name --port --service-refs --plugin-refs --db/--no-db --samples/--no-samples --force`	These flags belong to `netscript-dev plugin add <kind>`, not to public `netscript plugin add`.

Authentication plugin

The auth plugin is a first-class official plugin scaffolded exactly like the others — netscript plugin add auth installs plugins/auth/, registers the auth-api service on port 8094, and contributes plugins/auth/database/auth.prisma, which is migrated by the standard netscript db workflow alongside every other plugin schema. It composes one active backend at a time, chosen at runtime by the NETSCRIPT_AUTH_BACKEND env var.

Auth backend selection (NETSCRIPT_AUTH_BACKEND)
Name	Type	Description
`kv-oauth (default)`	`NETSCRIPT_AUTH_BACKEND=kv-oauth`	The default and the only interactive backend — full OAuth/OIDC redirect flow with KV-backed sessions. Needs provider env (`NETSCRIPT_AUTH_CLIENT_ID`, `NETSCRIPT_AUTH_CLIENT_SECRET`, `NETSCRIPT_AUTH_ISSUER`, `NETSCRIPT_AUTH_REDIRECT_URI`, …).
`workos`	`NETSCRIPT_AUTH_BACKEND=workos`	Non-interactive AuthKit backend — set `WORKOS_API_KEY`, `WORKOS_CLIENT_ID`, `WORKOS_COOKIE_PASSWORD`. The `signin`/`callback` endpoints return a typed unsupported-operation error (no interactive flow).
`better-auth`	`NETSCRIPT_AUTH_BACKEND=better-auth`	Non-interactive Prisma-backed backend — set `BETTER_AUTH_SECRET` and `DB_PROVIDER`. Like WorkOS, the interactive endpoints are unsupported.

Services & contracts

A NetScript workspace is contract-first: you define an oRPC contract, then a service implements it. The example users service runs on port 3001 and serves its RPC surface at /api/rpc/*.

Services and contracts
Name	Type	Description
`netscript service add`	`netscript service add orders --service-port 3002`	Add a new service workspace member and wire its contract. The example `users` service serves `/api/v1/users/` (and oRPC at `/api/rpc/`) on port 3001.
`netscript service list`	`netscript service list`	List the services configured in the workspace.
`netscript service generate`	`netscript service generate`	Regenerate the Aspire helper files from your service configuration.
`netscript contract add`	`netscript contract add orders`	Add a versioned oRPC contract (`oc.route().input(zod).output(zod)` + `implement()`) to the `contracts/` workspace.
`netscript contract list`	`netscript contract list`	List the contracts available in the workspace.

Database

The database workflow uses Prisma with a Deno runtime, and the engine is polyglot: netscript init --db postgres (the recommended default) or mysql, mssql, or sqlite. Postgres, MySQL, and SQL Server each run as an Aspire container resource; sqlite is file-backed and has no Aspire container. All of the container-backed engines require Aspire to be running — Aspire provisions the database, so start it first with cd aspire && aspire start. Plugin schemas (workers, sagas, triggers, auth) are picked up by the same generate / migrate pass. The full task walkthrough is in the database & migration how-to.

Database workflow (Aspire must be running)
Name	Type	Description
`netscript db init`	`netscript db init --name init`	Initialize database tooling and create the named migration. Requires Aspire up — it provisions Postgres through the AppHost.
`netscript db generate`	`netscript db generate`	Run database code generation — the Deno-runtime Prisma client (and zod) into `database/postgres/schema/.generated`. Includes plugin schemas such as `auth.prisma`.
`netscript db migrate`	`netscript db migrate`	Apply migrations against the provisioned database — including each plugin's contributed schema (e.g. the `auth_*` tables from `auth.prisma`).
`netscript db seed`	`netscript db seed`	Run the workspace seed scripts to populate initial data.
`netscript db status`	`netscript db status`	Show database migration / tooling status.
`netscript db studio`	`netscript db studio`	Open the database studio tool for browsing data.
`netscript db introspect / reset`	`netscript db reset`	Introspect the configured database, or reset it back to a clean state.

Code generation

After adding or changing plugins, regenerate the artifacts the project consumes so the registry and runtime schemas stay in sync.

Generate registries & schemas
Name	Type	Description
`netscript generate plugins`	`netscript generate plugins`	Generate the plugin registries from project source. Run this after every `plugin add` so the workspace picks up new contributions.
`netscript generate runtime-schemas`	`netscript generate runtime-schemas`	Generate runtime configuration schemas from registered plugin metadata.

Fresh UI

The frontend is copy-source: components are copied into your repo under apps/dashboard, and the code is yours to own and edit. See customize Fresh UI.

UI workspace tasks
Name	Type	Description
`ui:init`	`netscript ui:init --project-root apps/dashboard`	Initialize the fresh-ui design system into the dashboard app (copy-source components + tokens).
`ui:add`	`netscript ui:add --project-root apps/dashboard`	Copy an additional fresh-ui component into your repo — you own the copied source from that point.

Dev & workspace tasks

These are workspace deno tasks, not netscript subcommands — the day-to-day loop once the scaffold exists. Use --cwd <member> to target a specific workspace member.

Run and gate the workspace
Name	Type	Description
`Run the dashboard`	`deno task --cwd apps/dashboard dev`	Start the Fresh frontend (or let `aspire start` orchestrate it for you).
`Run a service`	`deno task --cwd services/users dev`	Start the example `users` oRPC service on port 3001.
`Type-check`	`deno task check`	Type-check the whole workspace.
`Lint`	`deno task lint`	Lint the workspace sources.
`Format`	`deno task fmt`	Apply the repo formatting (2-space, single-quote, lineWidth 100).
`Test`	`deno task test`	Run the workspace test suite.

Deploy

Deployment commands build and manage Windows Service artifacts from a deployment manifest. See deploy for the portability story, including the --no-aspire escape hatch and bare-deno task targets.

Deployment lifecycle
Name	Type	Description
`netscript deploy build`	`netscript deploy build`	Build the Windows Service deployment artifacts.
`netscript deploy package-cli`	`netscript deploy package-cli`	Compile a standalone deployment CLI artifact.
`netscript deploy install / start / stop`	`netscript deploy install`	Install, start, and stop Windows Services from a deployment manifest.
`netscript deploy status / logs`	`netscript deploy status`	Show service status and print deployment logs.
`netscript deploy upgrade / uninstall`	`netscript deploy upgrade`	Upgrade an installed deployment, or uninstall the services entirely.

The full surface

This page is curated for the common path. For every command, every subcommand, and every flag — generated directly from the published package — see the reference:

Generated CLI reference

The exhaustive, always-current command surface — every flag and subcommand, from the @netscript/cli package.

Quickstart

Install → init → aspire start → db → hit an endpoint, in about five minutes.

Database & migration

The full db workflow, with the Aspire-up dependency spelled out step by step.

Add authentication

Add the auth plugin, pick a backend via NETSCRIPT_AUTH_BACKEND, migrate auth.prisma, and wire the kv-oauth happy path.