Skip to main content
Aliases: placements, placement Commands that act on one placement take its ID either as a positional argument or with --id. If you omit it, the CLI opens an interactive picker, so always pass it in scripts. The server-* commands also open a picker for --server if you omit it.

​
Subcommands

  • list — List placements
  • get — Get placement details
  • create — Create a new placement
  • update — Change a placement’s image or update strategy
  • delete — Delete a placement
  • servers — List servers in a placement
  • server-reboot — Reboot a server in a placement
  • server-stop — Stop a server in a placement
  • server-reconcile — Rebuild a drifted server onto the placement’s image

​
list

List placements, optionally filtered by organization, project, or reservation.

​
Flags

FlagDescription
Organization ID
Project ID
Reservation ID
Emit the full JSON payload (mutually exclusive with -q)
jq filter for value extraction (see Query output with -q)

​
Example

​
get

Get details for a specific placement.

​
Flags

FlagDescription
Placement ID
Organization ID
Emit the full JSON payload (mutually exclusive with -q)
jq filter for value extraction (see Query output with -q)

​
create

Create a new placement. Accepts input from a JSON file or stdin, with an optional cloud-init configuration for the placed servers. Placements require an SSH certificate authority. Set it in the payload’s spec.serverSpec.sshCertificateAuthorityId field or pass --ssh-ca-id. Use nscale ssh-cas list to find the ID.

​
Flags

FlagDescription
Path to a JSON file
Read JSON from standard input
Path to a cloud-init YAML file
SSH certificate authority ID to bind
Preview actions and payload without persisting
Automatically confirm placement creation
Emit the full JSON payload (mutually exclusive with -q)
jq filter for value extraction (see Query output with -q)

​
Examples

​
update

Change a placement’s server image or update strategy. The CLI reads the placement, changes only the fields you pass, and writes it back, keeping every other field. Pass --image, --strategy, or both. All other placement fields are fixed after creation. Changing the image marks the placement’s servers as drifted. How they move onto the new image depends on the update strategy:
  • manual (the default for a new placement): servers keep their current image until you rebuild each one with server-reconcile.
  • rolling: the service rebuilds drifted servers for you, at most --max-unavailable at a time. --strategy rolling requires --max-unavailable, and --max-unavailable is only accepted with --strategy rolling.
If you omit --strategy, the placement keeps the strategy it already has, so an image change on a rolling placement starts a rollout.
Rebuilding a server onto a new image wipes its local disk. Under rolling, that happens to every server, --max-unavailable at a time, as soon as the update is accepted. Back up anything on local disk before you change the image.

​
Flags

FlagDescription
Placement ID
Organization ID
Image ID to converge the servers onto
Update strategy: manual or rolling. The API’s spellings, Manual and RollingUpdate, also work.
Servers rebuilt at once under : a count (1) or a percentage of the placement’s servers (25%, rounded up)
Preview actions and payload without persisting
Automatically confirm placement update
Emit the full JSON payload (mutually exclusive with -q)
jq filter for value extraction (see Query output with -q)

​
Examples

​
delete

Delete an existing placement.

​
Flags

​
Example

​
servers

List the servers in a placement.

​
Flags

FlagDescription
Placement ID
Organization ID
Emit the full JSON payload (mutually exclusive with -q)
jq filter for value extraction (see Query output with -q)

​
Example

After an image change under the manual strategy, list the servers that haven’t moved onto the new image yet:

​
server-reboot

Reboot an existing server in a placement. Use --hard for a hard reboot.

​
Flags

​
Example

​
server-stop

Stop an existing server in a placement.

​
Flags

​
Example

​
server-reconcile

Rebuild one drifted server onto the placement’s image. The server stays on the same host, but its local disk contents are lost. Use this after an image change under the manual update strategy to move servers onto the new image one at a time. If the server already runs the placement’s image, nothing changes.

​
Flags

​
Example

Reservations

Reserve GPU capacity and check available reservation units.