netscript command reference

The detailed verb-and-flag companion for the published netscript binary (@netscript/cli). Together with the curated CLI reference, these two pages cover every public command group and direct subcommand; this page concentrates the extended groups and flags while the curated page carries the everyday flows. For the package API surface (the embeddable helpers, not the command tree) see the @netscript/cli package page.

This page documents the public netscript binary — the CLI published as @netscript/cli and installed on your PATH — not any maintainer-only tree. Everything here is verified against netscript <group> --help. To confirm the exact spelling in your installed version, run netscript --help or netscript <group> --help.

The top-level groups are agent, config, deploy, init, contract, db, generate, marketplace, plugin, service, and the ui:* commands — each has a section below.

init — scaffold a workspace

netscript init [name] scaffolds a new NetScript workspace. The everyday walk-through is in the quickstart; every flag is:

Project init runs the existing agent installer after scaffolding by default, using the generated project root. Host detection honours project markers before the invoking environment and defaults to Claude Code; --host overrides detection. The deciding source is printed in text mode. Dry runs write no agent files, and --json retains its single scaffold result. Offline docs remain opt-in. The optional Aspire agent setup keeps its bounded timeout and reports a skip if unavailable. For an existing project, use netscript agent init to refresh integration idempotently.

agent — install and run agent tooling

netscript agent installs and runs the shared CLI × skills × MCP tooling. See Agent tooling for the mental model and the @netscript/mcp reference for the server's tool surface.

agent drift subcommands

The gate is the point. record appends an entry only when a diagnostic receipt for --resource exists, exited 0, and is less than 15 minutes old; the receipt itself is embedded in the entry. Anything else — no receipt, a failed one, a future timestamp, or a stale one — is refused with a non-zero exit and a message naming how to produce a fresh receipt (netscript plugin doctor --resource <name>, or the MCP doctor, telemetry, API introspection, or execute_command tools). A drift note therefore cannot be written from an agent's recollection of a run it did not just perform.

The same gate backs the MCP record_drift tool, so both surfaces refuse identically.

config — inspect and mutate configuration

netscript config reads and writes the resolved project configuration and manages runtime overrides.

config override subcommands

netscript config runtime publish <topic> <file> and netscript config runtime rollback <topic> <version> are lifecycle aliases for the matching config override verbs.

marketplace — discover and publish plugins

generate — code generation

Beyond generate plugins and generate runtime-schemas (covered in the CLI reference), the group also regenerates the Aspire helper layer.

For route generation, --project-root selects an explicit Fresh application directory and takes precedence over --app. Otherwise, --app selects a workspace member under apps/; from inside an app, that app is inferred, and a workspace with one app selects it automatically. Multiple apps require a selector. Missing or unknown targets fail before generation. Run netscript generate routes --app dashboard after adding, moving, or removing route files. Repeated runs leave unchanged outputs untouched. The command regenerates only the two derived modules; it does not reconcile authored router.ts entries or page bindings. See route lifecycle.

Plugin generated-surface check

Run netscript generate plugins --check --project-root . --format json to check every selected installed-plugin registry against the canonical bytes normal generation would write. The version-1 report contains producer, normalized project-relative path, ownership and SHA-256 digest for each output. producers includes every installed package and immutable version, including producers with zero outputs. inputs lists authored root authorities (including appsettings.json) and selected project source files with their digests. Authored inputs never appear as outputs.

Generation and check share installed-plugin manifest resolution, each plugin's selector and renderer, and the generated-source formatter. Output modules carry a producer marker. Missing output, extra files under the reserved .netscript/generated/plugin-*/ producer directories, changed producer or bytes return exit 1. SDK axis registries such as .netscript/generated/jobs.registry.ts are outside this check's scope. A removed producer's remaining files are extra outputs. Symlinks, invalid paths, producer overlaps, missing local manifests, unsupported inspection or failed rendering return a typed inspection-failure, also exit 1. current returns exit 0. No inspection failure falls back to normal generation. Check denies writes to the consumer project; canonical formatting stages only in the system temporary directory. --dry-run and --check are mutually exclusive.

Plugin manifests advertise byte inspection with runtimeRegistryGenerator.inspectionProtocol: 2. The CLI invokes the declared command with --inspect --inspection-protocol 2 --manifest-json <json> and the same generation arguments. The command emits one JSON document to stdout:

{
  "inspectionProtocol": 2,
  "registries": [
    {
      "registryPath": ".netscript/generated/plugin-example/items.registry.ts",
      "sourceFiles": ["items/example.ts"],
      "content": "export const registry = new Map();\n"
    }
  ]
}

Every declared target must appear exactly once; content: null means the shared selector would skip that target in normal generation. Regeneration removes an existing inactive target only when its bytes begin with that producer's exact marker; foreign or unmarked files are preserved and continue to report drift. Registry paths stay within the reserved producer directories and cannot claim authored configuration. The host validates and formats the returned module bytes before any project writes. Workers, triggers, sagas and AI implement protocol 2. Auth and streams declare an empty registry surface in their runtime manifests. An immutable published version returning HTTP 404 for its runtime manifest also declares zero outputs, including auth and streams 0.0.7. Missing local or source-member manifests and other HTTP failures fail closed. Protocol-1 source-only and legacy generators retain normal generation support; --check refuses them because source paths alone cannot certify output bytes. The inspection child runs with read permission and denies write, subprocess, network, environment, FFI and system permissions. Imports may resolve through Deno's module loader. Normal generation uses the consumer's configured lock semantics and may extend its module graph, just as other generator invocations do. Check and protocol-2 dry-run copy the configured consumer lock into the system temporary directory and use --frozen with --node-modules-dir=none. They retain locked dependency versions without modifying the lock or installing packages into the consumer project. A missing lock or generator graph returns an inspection failure with instructions to run netscript generate plugins first. Consumers must enable a project lock to certify registry bytes; inspection never resolves a fresh graph. Limits bound UTF-8 rendered bytes, source/output counts and child runtime. This check certifies generated bytes, not installed runtime health or every transitive import. Published-version Windows/Linux verification belongs to release validation.

Generated registries are derived artifacts. Add or replace job modules in workers/jobs/, then run netscript generate plugins; do not hand-edit .netscript/generated/**. Removing the official workers samples does not disable custom-job discovery.

plugin — extended verbs

The common plugin verbs (install, new, list, doctor, info, remove) are in the CLI reference. The full group also carries:

plugin ai is a pass-through, not a command group with its own verbs. NetScript strips --project-root, then runs the installed @netscript/plugin-ai package's CLI in a child deno run process and forwards every remaining argument verbatim, printing its output and propagating its exit code. The verb vocabulary therefore belongs to that plugin's release, not to this reference; see the @netscript/plugin-ai reference. Invoking it with no verb is an error.

plugin auth subcommands

The backends selectable here are the same ones read at runtime by NETSCRIPT_AUTH_BACKEND — see add authentication.

service — extended verbs

The common service add, service list, and service generate verbs are in the CLI reference. The full group also carries:

contract — extended verbs

The common contract add and contract list verbs are in the CLI reference. The full group also carries:

db — extended verbs

The everyday database workflow (init, generate, migrate, seed, status, studio, introspect, reset) is in the CLI reference — and all db commands require Aspire to be running (cd aspire && aspire start) unless you scaffolded a file-backed sqlite engine. The full group also carries the target-management and migration-history verbs:

ui:* — Fresh UI registry

ui:init and ui:add are in the CLI reference. The full set also lists, updates, and removes copied registry items:

Because Fresh UI is copy-source, ui:update only touches registry files you have not modified — your edits are never overwritten. See customize Fresh UI.

deploy — cloud and container targets

The CLI reference covers the Deno Deploy and OS service (Servy) paths. The deploy group also exposes a family of routed cloud and container targets, the packaging verbs, and artifact-copy and log verbs.

Discovering targets

deploy list reads the live registry, so it is the authoritative answer to which targets are registered and which operations their adapters advertise. The advertised set can be wider than the router's callable command set; use each target's help output or the routed-verb table below to see which verbs the CLI exposes. Ten targets are registered by default: azure-aca, azure-aks, azure-app-service, cloud-run, compose, deno-deploy, docker, kubernetes, linux-service, windows-service.

Routed cloud and container targets

These seven groups are generated by one router. Each is a thin command that parses flags and dispatches to a registry-resolved adapter; the adapter holds all target-specific logic.

The verb lists differ because a target only gets a subcommand for an operation it advertises. The router walks a fixed candidate list — plan, up, down, status, logs, rollback, secrets — and skips any operation missing from the adapter's operations, so a target never exposes a verb it cannot perform. The two container targets advertise status and logs; the five cloud targets do not.

Running a target group with no verb prints help, as every command group in the CLI does. That is the group's default action, not a sign that the target is unimplemented.

Every routed verb on every target shares the same flags: --project-root <dir>, --output-dir <dir> (directory for emitted deployment artifacts), --environment <name> (deployment environment passed to the target), --clear-cache (clear target deployment state and do not persist new values), and --non-interactive.

Packaging

package-cli bundles before compiling by default and falls back to compiling from source if the bundle step fails, so --no-bundle is a size/behaviour trade-off rather than a repair.

Artifact copy, logs, and upgrade

Aspire generated-surface check

Run netscript generate aspire --check --project-root . --format json to compare the selected AppHost, helpers and .netscript/aspire-cli.ts against their canonical generated bytes. The checker uses the same configuration selectors, template pipeline and formatter as netscript generate aspire. It does not invoke a project writer or format consumer files on disk. Root appsettings.json remains an authored authority; plugin install/remove owns plugin-reference reconciliation. Plugin install/remove and service add/remove own browser-auth wiring; generation reads the authored configuration and service sources without reconciling them. The AppHost's aspire/package.json is also project-owned: plugin, service and database mutation flows maintain its runtime dependencies, and netscript service generate repairs missing dependencies. Plain Aspire generation and inspection leave it unchanged. A current source inventory certifies generated bytes, not installed runtime dependencies or health.

The JSON Schema ships as @netscript/cli asset assets/schema/aspire-generated-surface.v1.json. Aspire and plugin checks share the versioned inventory entry contract, bounded reader, path validation, SHA-256 hashing and producer/byte comparison. The Aspire version 1 report contains version, generator, outputs, inputs, status, exitCode and drift. Each inventory entry contains generator, a normalized project-relative path, ownership (generated for outputs, authored for inputs), and digest (sha256:<hex>). Output digests include the producer declaration and exact UTF-8 bytes. Input authorities include root appsettings.json, existing netscript.config.ts/.js/.mjs, and deno.json. Plugin metadata and transitive configuration imports are also used by the shared selector; the input list names its root authorities rather than promising a transitive dependency inventory.

The generator owns aspire/apphost.mts, every leaf under aspire/.helpers/, and .netscript/aspire-cli.ts. SDK modules and Aspire settings are outside this command's output scope. Every selected output carries // @netscript-generated public.generate.aspire. The inventory rejects duplicate paths (including case overlaps), traversal and Windows path aliases, authored appsettings paths, missing AppHost or CLI runner producers, and declarations lost during formatting before any output can be certified or written. Init and database, service and plugin mutations use the same producer declaration and canonical formatting. Regenerate once if existing outputs lack that declaration or canonical formatting.

status: current exits 0. Missing outputs, extra helper leaves, a missing or foreign producer declaration, and byte drift produce status: drift, exit 1, with missing, extra, ownership and/or bytes findings. Linked files/directories, failed selection/rendering/formatting, permission failures and exceeded inspection limits produce status: inspection-failure, exit 1; this report certifies no outputs. Inspection findings include an optional message carrying the failure cause. Inspection configuration and metadata probes deny writes and subprocess launches. Normal generation retains recoverable degradation when a plugin metadata probe fails or times out. An inspection failure never retries through generation. The reader bounds each file to 16 MiB and the helper tree to 1,024 entries; rendering permits at most 256 outputs. Canonical formatting bounds the whole batch to 64 MiB of source characters, using one staging child and one Deno formatter. Staging stays outside the consumer project, including when inspection denies all writes.

This command covers Aspire generation; generate plugins --check covers installed-plugin registries. Published Windows/Linux release smoke remains follow-up work under #1912.