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

netscript --help

# Run the same CLI without installing anything
deno x jsr:@netscript/cli@0.0.7 --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.7

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

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.

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

Every init flag — including --app-name, --no-git, --force, --json, and --from <preset> — is spelled out in the command reference.

Aspire orchestration CLI

Run these commands from inside the aspire/ folder with the Aspire CLI (13.5.3):

Select a pinned Aspire executable

Set NETSCRIPT_ASPIRE_CLI to the executable name or path for your pinned toolchain. Unset or empty, it defaults to aspire. The generated aspire:otel and aspire:export tasks use it for both the primary command and the aspire ps dashboard fallback. NetScript's database operation executor and netscript agent init use the same variable.

The value is one executable, not a shell command with arguments. To activate a version manager, create an executable wrapper such as tools/aspire-pinned:

#!/bin/sh
exec mise exec -- aspire "$@"

Make it executable (chmod +x tools/aspire-pinned), then run from the workspace root:

export NETSCRIPT_ASPIRE_CLI="$PWD/tools/aspire-pinned"
deno task aspire:otel -- traces users

An absolute path also works in non-interactive shells without activating the version manager. Direct aspire commands and the aspire:start tasks still use your shell's PATH.

Refresh the generated helper with netscript generate aspire; do not hand-edit .netscript/aspire-cli.ts. This command also regenerates the AppHost helpers from root appsettings.json, and refuses a workspace scaffolded with --no-aspire. It does not rewrite root deno.json. Plugin install/update/remove and service add/remove also regenerate this helper. Existing workspace tasks with --allow-run=aspire --allow-read keep using aspire after regeneration, even in non-interactive runs: the helper reads the override only when env permission is already granted, and otherwise defaults to aspire without prompting. For an existing workspace, update its two telemetry task grants only when adopting the override:

{
  "aspire:otel": "deno run --allow-run --allow-env=NETSCRIPT_ASPIRE_CLI --allow-read .netscript/aspire-cli.ts otel",
  "aspire:export": "deno run --allow-run --allow-env=NETSCRIPT_ASPIRE_CLI --allow-read .netscript/aspire-cli.ts export"
}

These two tasks permit subprocess execution without an executable-name restriction so they can run the override; environment access is limited to NETSCRIPT_ASPIRE_CLI.

Run & iterate

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

Services & contracts

A NetScript workspace is contract-first: you define an oRPC contract, then a service implements it.

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.

The extended verbs — plugin sync, enable / disable / setup, item-add, and the plugin auth backend/provider/session subcommands — are in the command reference.

App-owned browser authentication

Auth installation defaults to the generated BFF topology. For an app that already owns its backend, session routes, and authentication bridge, set this in appsettings.json before installing auth or regenerating helpers:

{
  "NetScript": {
    "Apps": {
      "web": { "Auth": { "BrowserTopology": "authored" } }
    }
  }
}

BrowserTopology accepts scaffold (the default when omitted) or authored. With authored, plugin installation and lifecycle reconciliation skip that app's /auth action route and service-session example routes. They neither create nor replace its browser helpers. Pure netscript generate aspire regeneration also preserves the authored files, including when they are absent. netscript plugin doctor reports the app as using an authored browser topology; this reports ownership, not verification of your authentication implementation.

Only browser apps (Type: "app", including an omitted Type) select browser topology. Task, Tauri, and desktop entries do not cause shared helpers to be created alongside an authored browser app. Workspaces with no browser apps retain the legacy helper generation behavior.

In a multi-app workspace, browser apps using scaffold still receive the shared auth/bff.ts and auth/service.ts helpers. A scaffold-owned service policy still receives its bearer verifier and auth/service.ts; an authored service policy remains authoritative independently of the app setting. Switching to authored preserves existing generated files; remove unwanted files only after your own topology replaces their callers. See the 0.0.8 cookie migration.

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.

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.

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.

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.

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

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.