CLI reference
This is the cheat-sheet: which netscript command we reach for, grouped by task. Each
section lists the everyday spelling and stops there — every flag, subcommand, and
extended verb lives in the command reference, and the
embeddable TypeScript surface is on the @netscript/cli package page.
Every command here uses the public netscript <cmd> form backed by the published JSR
package; the vendored packages/cli/... path you may see in a local-source checkout is a
contributor-only shape.
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.6
netscript --help# Run the same CLI without installing anything
deno x jsr:@netscript/cli@0.0.6 --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.6netscript --version prints the installed CLI version; netscript --help and
netscript <group> --help (for example netscript db --help) show the exact flag
spelling your installed version ships.
The everyday flow
Most sessions follow the same shape, and the order matters: Aspire (step 2) must be up
before any db command (step 3).
netscript init lays down the whole workspace — contracts, an example service, plugins, and the Aspire layer.
cd aspire && aspire start brings up your database and Redis, and opens the dashboard at :18888. Do this before any db command.
netscript db init / generate / migrate / seed — only after Aspire is up.
netscript plugin install, then netscript generate plugins to wire the registry.
Mutation and regeneration map
Use this map before a command that writes. “Source of truth” is the declaration the command owns;
generated artifacts can be deleted and rebuilt from it unless the row says the command creates
workspace-owned source. “Preview” is deliberately explicit: do not assume every mutating command
accepts --dry-run.
| Command | Source of truth mutated | Generated artifacts | Runtime consumers | Preview |
|---|---|---|---|---|
netscript init |
New workspace choices and root configuration | Entire workspace, app/service/plugin/database skeletons, Aspire graph | Deno tasks, Fresh app, services, plugin runtimes, Aspire | --dry-run |
netscript config set |
Generated aspire/appsettings.json value |
None beyond the configuration write | AppHost generator and resources reading the setting | No |
netscript contract add / netscript contract add-route |
Workspace-owned versioned contract source | Version aggregate exports | Service handlers, SDK clients, OpenAPI/RPC routers | No |
netscript contract version add / netscript contract remove |
Versioned contract source | Version and root aggregate exports | Service and SDK imports | No |
netscript service add / netscript service set / netscript service remove |
Service workspace plus aspire/appsettings.json |
Contract aggregates, optional apps/<app>/lib/<service>.ts via --with-client, and Aspire helper files |
AppHost resource graph, typed callers | No |
netscript service ref add / netscript service ref remove |
Caller ServiceReferences in aspire/appsettings.json |
Aspire helper files | AppHost environment/reference injection | No |
netscript db add / netscript db remove |
Database target configuration and workspace membership | Aspire configuration and AppHost helpers | Prisma tasks, services, Aspire resources | No |
netscript db init / netscript db migrate |
Prisma schema and migration history | Migration directories and generated client inputs | Prisma engine and application repositories | No; database operation |
netscript db generate |
Prisma schema, including plugin contributions | Prisma client and Zod output | Services, plugins, repositories | No |
netscript plugin install / netscript plugin update / netscript plugin remove |
Plugin dependency and host registration | Workspace glue, plugin registries, Aspire helpers | AppHost and plugin service/runtime discovery | install --dry-run; others no |
netscript generate plugins |
Installed plugin manifests and project source | .netscript/generated plugin registries |
Plugin host and generated imports | --dry-run |
netscript generate runtime-schemas |
Runtime topic declarations | Runtime-config JSON Schema files | Editors, validators, runtime override tooling | --dry-run |
netscript generate aspire |
aspire/appsettings.json |
AppHost helper files | Aspire AppHost | No |
netscript ui:init / netscript ui:add |
Registry selection | Workspace-owned components, pages, islands, styles, and tokens | Fresh app and its Vite build | No |
netscript ui:update / netscript ui:remove |
Installed registry inventory and unmodified copied files | Updated or removed copy-source UI files | Fresh app and its Vite build | No |
netscript deploy build / target plan |
Deployment manifest plus project entrypoints | Target deployment artifacts or an emitted plan | Target runtime or service manager | plan is non-deploying |
netscript deploy up / deploy install / lifecycle verbs |
Deployment target or service-manager state | Provider/service-manager state; target-dependent local artifacts | Deployed services | Target-dependent; check --help |
Read commands (list, get, inspect, status, logs, doctor) are omitted because they do not
mutate project or provider state. Commands that invoke an external database or cloud provider say
so in the final column; a filesystem-only --dry-run would not safely model those effects.
Scaffold a workspace
| Name | Type | Description |
|---|---|---|
Create a workspace |
netscript init my-app |
Scaffold everything — contracts, plugin registry, Fresh app, a default Redis cache, and the Aspire layer. On a terminal it prompts for whatever you omit (name, database, service, cache). |
Preview first |
netscript init my-app --dry-run |
Print every file and directory the scaffold would create, and write nothing. |
Fully specified, no prompts |
netscript init my-app --db postgres --service --service-name users --yes |
Postgres database support, an example oRPC users service on its assigned port, defaults for the rest. --yes accepts defaults, --ci is non-interactive; both engage automatically when stdin is not a terminal. |
Pick a database engine |
netscript init my-app --db postgres |
postgres (recommended), mysql, mssql, sqlite, or none — the default is no database unless you pass --db. |
Skip Aspire |
netscript init my-app --no-aspire |
Scaffold without the .NET Aspire footprint; start the Fresh app directly with deno task --cwd apps/dashboard dev. |
Tune the rest |
--cache-backend garnet · --model-name Product · --path ./apps · --editor zed |
Cache backend (redis default, garnet, or app-level deno-kv; --cache=false for none), the Prisma model name for the scaffolded CRUD surface, the target directory, and editor settings. |
Every init flag — including --app-name, --no-git, --force, --json, and
--from <preset> — is spelled out in the command reference.
Run & iterate
These are workspace deno tasks, not netscript subcommands — the day-to-day loop once
the scaffold exists.
| Name | Type | Description |
|---|---|---|
Orchestrate everything |
cd aspire && aspire start |
Bring up the database, Redis, services, and plugin processors, with the dashboard at :18888. |
Run the dashboard alone |
deno task --cwd apps/dashboard dev |
Start the Fresh frontend directly (or let aspire start orchestrate it). |
Run a service alone |
deno task --cwd services/users dev |
Start the example users oRPC service on its assigned port. |
Check, lint, test |
deno task check · deno task lint · deno task fmt · deno task test |
Type-check, lint, format, and test the whole workspace. |
Services & contracts
A NetScript workspace is contract-first: you define an oRPC contract, then a service implements it.
| Name | Type | Description |
|---|---|---|
Add a service |
netscript service add --name orders --port 3002 --with-client |
Add a service workspace member, its v1 contract, the Aspire registration, and apps/ |
Add a contract |
netscript contract add catalog-items |
Create contracts/versions/v1/catalog-items.contract.ts from the oRPC contract template and regenerate the v1 aggregate exports. |
Add a route + handler |
netscript contract add-route · netscript service add-handler |
Append a typed procedure to a contract, then bind it with a compiling service handler stub. |
See what exists |
netscript service list · netscript contract list · netscript contract inspect |
List services, list v1 contract modules (and whether each has a matching service), and inspect a contract's procedures and schemas. |
Regenerate Aspire helpers |
netscript service generate |
Regenerate the Aspire helper files from your service configuration. |
The full groups — service set / remove / ref add, contract remove /
version add, and every flag — are in the command reference.
Plugins
Plugins add capabilities — background workers, durable sagas, webhook triggers, durable streams, authentication. Public install adds the plugin package dependency, emits workspace-owned glue that imports it, and registers its contributions; the plugin's internals stay in the installed dependency.
| Name | Type | Description |
|---|---|---|
Install an official plugin |
netscript plugin install workers --name workers |
Bare aliases (workers, auth, …), scoped specs (@netscript/plugin-workers), and jsr: specs all work. After auth, pick the runtime backend with NETSCRIPT_AUTH_BACKEND — see add authentication. |
Wire the registry |
netscript generate plugins |
Regenerate the plugin registries from project source. Run this after every plugin install. |
Check health |
netscript plugin list · netscript plugin doctor · netscript plugin info workers |
List registered plugins, run the wiring sanity check, and show a single plugin's details. |
Author your own |
netscript plugin new billing |
Scaffold a new two-tier plugin: a JSR-publishable core package plus a thin connector. See author a plugin. |
Discover & maintain |
netscript marketplace search |
Search the plugin marketplace, re-pin and regenerate an installed plugin, or remove one and update workspace registration. |
Configure the AI plugin |
netscript plugin ai |
Configure AI tools, agents, models, providers, and MCP servers. A pass-through: every argument after the verb is forwarded verbatim to the installed @netscript/plugin-ai CLI, so its verbs are documented by that plugin, not here. Only --project-root is consumed by NetScript. |
The extended verbs — plugin sync, enable / disable / setup, item-add, and the
plugin auth backend/provider/session subcommands — are in the
command reference.
Database
The database workflow uses Prisma with a Deno runtime, and every command below requires
Aspire to be running first (cd aspire && aspire start) — sqlite being the file-backed
exception. Plugin schemas (workers, sagas, triggers, auth) are picked up by the
same generate / migrate pass. The walkthrough is the
database & migration how-to.
| Name | Type | Description |
|---|---|---|
Initialize + first migration |
netscript db init --name init |
Initialize database tooling and create the named migration. |
Generate the client |
netscript db generate |
Generate the Deno-runtime Prisma client (and zod) — including plugin schemas such as auth.prisma. |
Migrate & seed |
netscript db migrate · netscript db seed |
Apply migrations (including each plugin's contributed schema), then run the workspace seed scripts. |
Inspect |
netscript db status · netscript db studio |
Show migration/tooling status, or open the database studio for browsing data. |
Recover |
netscript db introspect · netscript db reset |
Introspect the configured database, or reset it back to a clean state. |
Multiple databases |
netscript db add |
Add a second database workspace to an existing project and list registered targets. |
The scaffolded workspace also defines Aspire-less deno task db:* tasks
(db:generate, db:migrate, db:seed, db:studio, …) inside database/<engine>/ that
run Prisma directly — the form to use in deno-only or CI jobs. The target-management and
migration-history verbs (db deploy, validate, resolve, remove) are in the
command reference.
Generate
After adding or changing plugins or configuration, regenerate the artifacts the project consumes.
| Name | Type | Description |
|---|---|---|
Plugin registries |
netscript generate plugins |
Regenerate the plugin registries from project source — the post-install step. |
Runtime config schemas |
netscript generate runtime-schemas |
Generate JSON Schema files for runtime configuration topics. |
Aspire helpers |
netscript generate aspire |
Regenerate the Aspire AppHost helpers from appsettings.json without re-scaffolding. |
Related: netscript config inspect / get / set read and write the resolved project
configuration, and netscript config override manages versioned runtime overrides — the
full subcommand table is in the command reference.
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.
| Name | Type | Description |
|---|---|---|
Initialize the design system |
netscript ui:init --project-root apps/dashboard |
Copy the fresh-ui components and tokens into the dashboard app. |
Add a component |
netscript ui:add |
Copy an additional registry item — you own the copied source from that point. |
List & maintain |
netscript ui:list · netscript ui:update · netscript ui:remove |
List registry items, update only files you have not modified, or remove a copied item. |
Deploy
Deploy carries several paths: the Deno Deploy cloud target, the OS service (Servy)
path, the container and cloud targets routed through Aspire, and two packaging verbs
for shipping a binary. netscript deploy list prints every registered target with the
operations it advertises — start there rather than guessing. See
deploy for the portability story.
| Name | Type | Description |
|---|---|---|
Discover targets |
netscript deploy list [--json] |
List every registered deploy target with its label and advertised operations. --json emits machine-readable descriptors. |
Deno Deploy: preflight |
netscript deploy deno-deploy plan |
Run the unstable-API guard (scans for Deno.openKv, Deno.cron, BroadcastChannel, Temporal) without pushing. The same guard blocks up --prod on a violation; a preview push warns but proceeds. |
Deno Deploy: lifecycle |
netscript deploy deno-deploy up [--prod] · down · status · logs |
Push, delete, and inspect the deployment. A thin router over the native deno deploy CLI — it must be on your PATH and handles authentication. |
OS service: build |
netscript deploy build |
Compile services and generate the deployment artifacts from a deployment manifest via Servy. |
OS service: lifecycle |
netscript deploy install · start · stop · status · logs · upgrade · uninstall |
Register, run, inspect, upgrade, and remove OS services from the manifest. |
Containers: Docker & Compose |
netscript deploy docker |
Aspire-backed container targets. Both expose plan · up · down · status · logs — the bare group prints help, as every command group does, but the verbs run against a real adapter. |
Cloud targets |
netscript deploy kubernetes · azure-aca · azure-app-service · azure-aks · cloud-run |
Aspire-backed cloud targets, each exposing plan · up · down. See the command reference for why their verb list is shorter. |
Package a desktop app |
netscript deploy desktop package · netscript deploy desktop release |
Package an enabled desktop app into native Deno Desktop formats for the host OS/arch by default (or an explicit target), and prepare, sign, and serve a native release. |
Package the CLI |
netscript deploy package-cli |
Compile the NetScript CLI into a self-shippable Windows .exe. Flags: -o, --output-dir <dir> (default ./.deploy/windows), --target <triple> (default x86_64-pc-windows-msvc), --no-bundle, -v, --verbose. |
The shared flags (--org, --app, --entrypoint, --env-file, --project-root), the
per-target verb flags, and the artifact-copy verbs are in the
command reference.
Agent tooling
| Name | Type | Description |
|---|---|---|
Install agent tooling |
netscript agent init |
Install NetScript MCP, consumer tools, and skills. Use --editor none|zed|vscode to apply editor-native setup to a new or existing project; one existing editor directory is detected by default. Use --host claude|vscode|all for agent hosts and --with-docs for the exact-version offline corpus. |
Run the MCP server |
netscript agent mcp |
Start the NetScript MCP server over standard input/output. |
Record drift |
netscript agent drift record --resource |
Record an evidence-gated drift note after a fresh successful diagnostic pass. The record is rejected unless the evidence for --resource is present on disk, so it cannot be written from memory. --details <text> is optional. |
See Agent tooling for the mental model.
The full surface
This page is the curated common path; together with the detailed
command reference, the two-page set covers every public command group
and direct subcommand. For the embeddable package API, use the
@netscript/cli package page.