NuPaaS Docsnupaas nodes
platform node manages the machines in your fleet — registering new ones, taking them out of rotation, and removing them.
Command name
platform node has four subcommands: add, list, drain and remove.
node add
Generates a bootstrap token and prints the two steps to run on the machine you are enrolling. The CLI does not connect to your machine itself — you run the printed install command there.
platform node add
platform node add --role control-plane
platform node add --json| Parameter | Type | Description |
|---|---|---|
| --role | string | worker or control-plane. Default: worker. |
| --wait | boolean | Poll until the server reports in. Default: true — pass --wait=false to return immediately. |
| --org | string | Organization ID. Defaults to the organization in your config. |
| --json | boolean | Emit the token payload as JSON instead of printed instructions. Default: false. |
Unlike most flags in this CLI, --wait defaults to on here. After printing the instructions the command polls for up to two minutes and reports the new server's ID, hostname and status once it registers. If the window elapses it says so and exits — the server may still register afterwards.
node list
Lists the servers in your fleet with hostname, status, external address, provider and role.
platform node list
platform node list --json| Parameter | Type | Description |
|---|---|---|
| --org | string | Organization ID. Defaults to the organization in your config. |
| --json | boolean | Emit raw JSON instead of a table. Default: false. |
The table shortens server IDs. drain and remove both take a server ID as a positional argument, so use --json to get the full value when scripting.
node drain
Puts a server into draining state so workloads move off it. Drain before maintenance or before removing a server, so traffic is shed in an orderly way rather than dropped.
platform node drain nod_01H8XK2M4Q7Z6YB3V9NRWTC5AF
platform node drain nod_01H8XK2M4Q7Z6YB3V9NRWTC5AF --json| Parameter | Type | Description |
|---|---|---|
| nodeId | argument | Required positional argument. The server to drain. |
| --json | boolean | Emit the resulting server state as JSON. Default: false. |
Draining is not instantaneous. The command returns once the server has been marked as draining; watch platform node list to see it settle.
node remove
Removes a server from the fleet. The command prompts for confirmation and defaults to no.
platform node remove nod_01H8XK2M4Q7Z6YB3V9NRWTC5AF
platform node remove nod_01H8XK2M4Q7Z6YB3V9NRWTC5AF --force| Parameter | Type | Description |
|---|---|---|
| nodeId | argument | Required positional argument. The server to remove. |
| --force | boolean | Skip the confirmation prompt. Default: false. |
| --json | boolean | Emit a JSON result object instead of a message. Default: false. |
--force exists so that automation can remove servers without a terminal attached. Drain first: removing a server that is still serving traffic drops whatever it was serving.
Server groups
A server group is a named set of servers you can act on together. platform node-groups — plural, and a distinct top-level command — manages them.
platform node-groups list --json
platform node-groups create --name edge-eu --app-name checkout
platform node-groups add-node --id ngp_01H8XK2M4Q --node-id nod_01H8XK2M4Q
platform node-groups deploy --id ngp_01H8XK2M4Q --target checkout
platform node-groups deploy-status --id ngp_01H8XK2M4QThe full subcommand set is list, get, create, update, delete, add-node, remove-node, deploy and deploy-status.
Rolling out to a group
node-groups deploy starts a batch rollout of one component across every server in the group and returns a batch identifier. node-groups deploy-status reports the overall status plus a per-server breakdown, including the error on any server that failed — so a partial rollout is visible rather than silently averaged away.
Services on a server
platform native-services inspects the services running directly on a server. Every subcommand requires --node.
platform native-services list --node nod_01H8XK2M4Q --json
platform native-services get --node nod_01H8XK2M4Q --service svc_01H8XK2M4Q| Parameter | Type | Description |
|---|---|---|
| --node | string | Required on every subcommand. The server to inspect. |
| --service | string | Required on get, harden and inspect. The service to act on. |
| --json | boolean | Emit raw JSON instead of a table. Default: false. |
The subcommands are list, get, harden and inspect.