Command-line reference

Pre-release documentation.

Commands may change. The binaries are named gridweaved, gridweave, gridweave-admin and gridweave-agent. GridWeave is under construction and not released: there is no download, no installer package and nothing is code-signed.

The programs

Four programs are built from the product repository today. They were renamed in feature 043 from nsd, nsctl, nsadmin and nsagent; nothing was released under the earlier names, so there is no compatibility layer. This page was written from each program's own usage text and flag definitions. What did not change: the NS_* configuration variables, NSAGENT_ENROLLMENT_TOKEN and the NSCTL_* variables, the ns.* protocol packages and the ns_ database roles.

Programs, the earlier names they replace and what they do.
Program	Earlier name	Runs on	Purpose
`gridweaved`	`nsd`	Server	The server: one binary, one role per service
`gridweave-admin`	`nsadmin`	Server host	Operator tool; talks to the database and key store directly
`gridweave`	`nsctl`	Your workstation	User client: personal access token, devices, scripts, terminal, file copy
`gridweave-agent`	`nsagent`	Each managed device	The endpoint agent: enrol, run, install as a service, verified updates

Exit status is 0 for success, 1 for a failure and 2 for wrong usage in gridweaved, gridweave-admin and gridweave. gridweaved also exits 3 when a role is not implemented, and gridweave-agent uses 2 for configuration problems or a device that is not enrolled and 3 when the server no longer accepts the device.

gridweaved: the server

gridweaved <role> [--config file]
gridweaved version

The roles are api, agent-gateway, relay, worker, web, amt, bridge and all-in-one (every implemented role in one process with an embedded bus, for development and small installs). amt runs only when amt.enabled is set and has been tested against a simulator only. bridge is not built and exits with code 3.

--config names a YAML file. It is optional, because NS_* environment variables override the file: the key path in upper case joined with underscores (http.listen is NS_HTTP_LISTEN). Unknown keys are refused and named. The published schema is server/schema/config.schema.json. Secrets are given as env:NAME or file:/path. See Deployment for the main keys.

gridweave-admin: the operator tool

Most commands need the database (kms generate-master-key and objstore check need none); all read the same configuration as gridweaved (--config file and NS_* variables, notably NS_DATABASE_URL). Migrations run with the configured login, which then owns the schema.

gridweave-admin commands (usage text of server/cmd/gridweave-admin).
Command	What it does
`migrate`	Apply pending schema migrations. Refuses, and prints the SQL, if the three database group roles are missing
`schema-version`	Print the applied schema version
`bootstrap --username NAME [--password-stdin]`	Create the `default` tenant and the first platform administrator. Does nothing if one exists. Without `--password-stdin` it generates a password and prints it once
`pki init`	Create the certificate authority (root, Device, Service and Command issuers) and the command-signing key. Safe to repeat: run it once per installation and again after an upgrade
`pki status`	List the issuers with their expiry and fingerprint
`pki export-root FILE`	Write the root certificate (PEM) and print `root fingerprint (agent ca_pin)`
`tenant create --slug S --name N`	Create an empty tenant
`account create --tenant T --user U [--password-stdin] [--tenant-admin]`	Create an account. `--tenant-admin` also grants the tenant-admin and device-admin roles
`account reset --tenant T --user U [--password-stdin]`	New password; second factors and locks removed; sessions ended
`account grant-platform-admin \| revoke-platform-admin --tenant T --user U`	Change platform administrator rights
`audit verify`	Verify the audit hash chain of every tenant and of the platform
`kms status`	Driver, reachability, key versions and fingerprints, stored values by wrapping form
`kms migrate --to openbao\|file-encrypted [--dry-run] [--batch N] [--verify-sample N]`	Move keys to another driver and re-wrap stored secrets; certificates stay unchanged
`kms rotate [--dry-run] [--batch N] [--no-rewrap]`	New version of the wrapping key, then re-wrap stored secrets
`kms rewrap [--dry-run] [--batch N]`	Re-wrap stored secrets that are not on the newest wrapping key version
`kms generate-master-key [--out FILE]`	A master key for the `file-encrypted` driver, shown once or written to a new file with mode 0600. Needs no database
`objstore check`	Write, read back, list and delete a probe object in the configured object store. Needs no database
`releases import --dir DIR`	Verify a signed agent release and import it for download (needs `updates.trusted_keys_file`)
`releases list`	The imported releases, newest first, with expiry
`version`	Print the version and build

Defaults: --tenant is default for the account commands, and --batch is 100 rows per transaction. A password rule violation is reported with exit status 2. Passwords are read from standard input, never from a flag.

gridweave: the user client

Create a personal access token in the web application under Account, then sign in once. The token is never taken from a flag.

gridweave login --server https://HOST --token-file FILE
gridweave whoami [--permissions]
gridweave devices list [--group ID] [--tag TAG] [--query TEXT] [--online | --offline] [--limit N]
gridweave devices show DEVICE
gridweave run DEVICE... (-c SCRIPT | --script-file FILE) [--interpreter sh|powershell|cmd] [--run-as agent|user|user_first] [--timeout SECONDS] [--no-wait]
gridweave shell DEVICE
gridweave cp SRC DST [--overwrite] [--resume] [--quiet]
gridweave logout

A DEVICE is an id or an exact name; if several devices share a name, gridweave lists their ids and asks you to use one. cp needs exactly one side written as DEVICE:PATH.

Commands (usage text and flag definitions of server/internal/gridweave).
Command	Behaviour
`login`	Reads the token from `--token-file FILE` (`-` for standard input), `--token-stdin`, `NSCTL_TOKEN` or a hidden prompt. It must start with `gwp_`. The server checks it before it is stored
`logout`	Removes the stored token. The token stays valid on the server until you revoke it under Account
`whoami`	Shows user, tenant, authentication method and id; `--permissions` adds the permissions the token holds
`devices list \| show`	The devices you may see, with the filters above (`-q` is short for `--query`)
`run`	Runs a script on one or more devices as a job and waits. `--timeout` is 1 to 3600 seconds (default 60) and the script 1 to 65536 bytes; `--run-as` defaults to `agent`. Exits with the script's own code for one device, and 1 if any of several failed. `--no-wait` prints the job id and returns
`shell`	Interactive terminal through the relay, with the device user's consent if the policy asks for it
`cp`	Copies a file to or from a device over a files session, with progress, `--resume` after an interruption and a whole-file SHA-256 check

Common flags, accepted by every command.
Flag	Meaning
`--server URL`	The server origin (stored by `login`). Plain `http` is accepted only for a loopback address
`--tenant SLUG`	The tenant; the default tenant if omitted
`--ca-file FILE`	Trust this certificate authority for the server
`--insecure`	Do not verify the server certificate (development only; prints a warning)
`--proxy URL`	Use this proxy (default: `HTTPS_PROXY`)
`-o`, `--output`	`table`, `json` or `csv`

Configuration. login stores the server, tenant, token and trust settings in gridweave/config.json under your user configuration directory, or at the path in NSCTL_CONFIG. The file is written with mode 0600 in a 0700 directory, and a file readable by others is refused. The environment variables NSCTL_SERVER, NSCTL_TENANT, NSCTL_TOKEN and NSCTL_CA_FILE override the file, and flags override both.

What is not built or not verified.

Login by device code or by password and second factor, an operating-system keychain, events watch and port-forward are not built. shell and cp were proved against fake agent legs and a fake console, and the agent side was proved on macOS only; no test drives gridweave against the real agent, and Windows was cross-compiled, not run. No proxy was tested.

gridweave-agent: the endpoint agent

gridweave-agent --version
gridweave-agent --check-config <file>
gridweave-agent enroll --config <file> [--token-file <path>]
gridweave-agent run --config <file>
gridweave-agent install --server-url <url> --tenant <slug> --ca-file <file>
                [--ca-pin <sha256>] [--token-file <path>] [--root <dir>]
                [--no-start] [--skip-enroll]
gridweave-agent uninstall [--root <dir>] [--keep-identity]
gridweave-agent status [--root <dir>]
gridweave-agent update verify|stage|apply|rollback|status

enroll obtains the device certificate. The enrolment token comes from the environment variable NSAGENT_ENROLLMENT_TOKEN or from --token-file, never from the command line.
run connects to the server and stays connected until it receives SIGINT or SIGTERM.
install copies the agent to /usr/local/lib/gridweave-agent, writes the configuration, enrols the device and registers and starts the service (systemd on Linux, launchd on macOS). Run it as root. With --root DIR everything is written below DIR and nothing is registered or started; --no-start writes everything and does not register or start; --skip-enroll does not enrol. Running it again keeps an enrolled device enrolled.
uninstall stops and removes the service and what install wrote, the device identity too unless you pass --keep-identity.
status prints installed, enrolled and running, and exits 0 when the agent is installed and running (with --root: when installed).
update checks a signed update manifest against the update-signing keys pinned into the build and, on Linux and macOS, stages and applies a verified binary by hand: update verify --manifest FILE [--artifact FILE], update stage --manifest FILE --artifact FILE, update apply [--no-restart], update rollback [--no-restart], update status. These commands work on local files and download nothing. Separately, an installed agent asks the server for a release by itself (every 900 seconds by default, update_check_seconds in agent.toml), and only when a rollout or policy offers it one; it then verifies and applies the update with the same checks and rolls back if the new build does not reconnect (staged rollouts). The update watchdog subcommand is run by the agent's own rollback timer, not by you. Self-update is proven on Linux under systemd; the macOS launchd job and Windows are unverified.

Exit status: 0 success, 1 failure, 2 usage, configuration or not enrolled, 3 the server no longer accepts this device (revoked or unknown). On Windows the agent installs to C:\Program Files\gridweave-agent with state in C:\ProgramData\gridweave-agent and is registered with the Service Control Manager; that path was never run with a real enrolment. The agent refuses to start when its configuration file can be written by group or others. See Deployment for a worked install.

releasesign: sign an agent release

releasesign is a repository tool (tools/cmd/releasesign, standard-library Go) that makes and signs the release manifest the agent verifies. It uses Ed25519 and is meant to run with an offline key.

releasesign keygen   -id ID -out PRIVATE_KEY_FILE [-pub PUBLIC_KEY_FILE]
releasesign manifest -dir DIR -version V [-product P] [-channel C] [-created RFC3339] [-valid-days N] [-out FILE]
releasesign sign     -key PRIVATE_KEY_FILE -key-id ID -manifest FILE [-in SIGNED] -out SIGNED
releasesign verify   -pub PUBLIC_KEY_FILE -signed FILE [-dir DIR]

keygen refuses to write a private key inside a Git work tree and refuses to overwrite a file. Build the tool with cd tools && go build -o releasesign ./cmd/releasesign. The keys committed in the product repository are development keys, the offline signing ceremony has not been done and nothing is code-signed. Import a signed release on the server with gridweave-admin releases import --dir DIR.

Test tools

The repository also builds gridweave-load (a simulated fleet), gridweave-conform (33 gateway conformance cases), amtsim (a simulated Intel AMT device) and relaydevagent (a development program that answers relay offers). They are test tools, not part of an installation, and their flags are not documented here.