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:

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.

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