# 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](https://rickylabs.github.io/netscript/reference/cli/commands/), and the embeddable TypeScript surface is on the [`@netscript/cli` package page](https://rickylabs.github.io/netscript/reference/cli/). 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.

> Database commands need Aspire running first
>
> The
>
> netscript db ...
>
> commands provision and talk to your database
>
> through Aspire
>
> .
>
> cd aspire && aspire start
>
> brings up Postgres and Redis via Docker and opens the dashboard at
>
> :18888
>
> — do this
>
> before
>
> any
>
> db
>
> command (
>
> sqlite
>
> is the file-backed exception with no container). Run a
>
> db
>
> command with Aspire down and it fails to find the database — the “aspire start failed: project file does not exist” error almost always means exactly this. See the
>
> database & migration how-to
>
> .

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

```bash
# Installs a `netscript` command on your PATH
deno install --global --allow-all --name netscript jsr:@netscript/cli@0.0.6

netscript --help
```

```bash
# Run the same CLI without installing anything
deno x jsr:@netscript/cli@0.0.6 --help
```

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

`netscript --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).**

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 and Redis, and opens the dashboard at :18888. Do this before any db command.

3 · Database

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

4 · Extend & generate

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

**netscript init**

| 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](https://rickylabs.github.io/netscript/reference/cli/commands/).

## Run & iterate

These are workspace `deno task`s, not `netscript` subcommands — the day-to-day loop once the scaffold exists.

**Run and gate the workspace**

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

**Services and contracts**

| 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//lib/orders.ts with a typed client and query factories. |
| `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](https://rickylabs.github.io/netscript/reference/cli/commands/).

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

**Plugin lifecycle**

| 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](https://rickylabs.github.io/netscript/identity-access/how-to/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](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/author-a-plugin/). |
| `Discover & maintain` | `netscript marketplace search  · netscript plugin update  · netscript plugin remove ` | 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  [...args]` | 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](https://rickylabs.github.io/netscript/reference/cli/commands/).

## 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](https://rickylabs.github.io/netscript/data-persistence/how-to/database-migration/).

**Database workflow (Aspire must be running)**

| 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  · netscript db list` | 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](https://rickylabs.github.io/netscript/reference/cli/commands/).

## Generate

After adding or changing plugins or configuration, regenerate the artifacts the project consumes.

**Code generation**

| 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](https://rickylabs.github.io/netscript/reference/cli/commands/).

## 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](https://rickylabs.github.io/netscript/web-layer/how-to/customize-fresh-ui/).

**UI registry commands**

| 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  --project-root apps/dashboard` | 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](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/deploy/) for the portability story.

**Deploy commands**

| 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  · netscript deploy compose ` | 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](https://rickylabs.github.io/netscript/reference/cli/commands/) 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](https://rickylabs.github.io/netscript/reference/cli/commands/).

## Agent tooling

**AI agent commands**

| 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  --summary ` | 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](https://rickylabs.github.io/netscript/ai/agent-tooling/) for the mental model.

## The full surface

This page is the curated common path; together with the detailed [command reference](https://rickylabs.github.io/netscript/reference/cli/commands/), the two-page set covers every public command group and direct subcommand. For the embeddable package API, use the [`@netscript/cli` package page](https://rickylabs.github.io/netscript/reference/cli/).

[Command reference  The detailed companion for extended command groups and flags; use it with this curated page for the complete public root/direct-command surface.](https://rickylabs.github.io/netscript/netscript/reference/cli/commands/)

[Quickstart  Install → init → aspire start → db → hit an endpoint, in about five minutes.](https://rickylabs.github.io/netscript/netscript/quickstart/)

[Database & migration  The full db workflow, with the Aspire-up dependency spelled out step by step.](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/database-migration/)

[@netscript/cli package  The package API reference — the embeddable TypeScript surface, not the command tree.](https://rickylabs.github.io/netscript/netscript/reference/cli/)

[Glossary](https://rickylabs.github.io/netscript/netscript/glossary/)