> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nscale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Placements

> Manage GPU placements.

**Aliases:** `placements`, `placement`

Commands that act on one placement take its ID or name 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 take the placement the same way, and also open a picker for `--server` if you omit it. Placement, project, reservation, and server flags accept a name as well as an ID.

## Subcommands

* [list](#list) — List placements
* [get](#get) — Get placement details
* [create](#create) — Create a new placement
* [update](#update) — Change a placement's image or update strategy
* [delete](#delete) — Delete a placement
* [server list](#server-list) — List servers in a placement
* [server reboot](#server-reboot) — Reboot a server in a placement
* [server stop](#server-stop) — Stop a server in a placement
* [server reconcile](#server-reconcile) — Rebuild a drifted server onto the placement's image

> [!NOTE]
>
> CLI v7.0.0 moved the server commands under `server`: `servers` became `server list`, and `server-reboot`, `server-stop`, and `server-reconcile` became `server reboot`, `server stop`, and `server reconcile`. The old names still work but are hidden from help.

***

## list

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

**Aliases:** `list`, `ls`

```bash theme={null}
nscale placements list [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td>`--org string`</td><td>Organization ID or name</td></tr>
    <tr><td>`--project string`</td><td>Project ID or name</td></tr>
    <tr><td>`--reservation string`</td><td>Reservation ID or name</td></tr>

    <tr>
      <td>
        `--json`
      </td>

      <td>Emit the full JSON payload (mutually exclusive with `-q`)</td>
    </tr>

    <tr>
      <td>
        `-q, --query stringArray`
      </td>

      <td>jq filter for value extraction (see [Query output with `-q`](https://docs.nscale.com/docs/cli/query-output))</td>
    </tr>

    <tr>
      <td>
        `--limit int`
      </td>

      <td>Show at most N results (client-side; every result is still fetched). Cuts before `-q`. `0` for all</td>
    </tr>
  </tbody>
</table>

### Examples

```bash theme={null}
nscale placements list --org <org-id> --reservation <reservation-id>
nscale placements list --reservation <reservation-id> -q '.[].metadata.id' -q '.[].metadata.name'
```

***

## get

Get details for a specific placement.

```bash theme={null}
nscale placements get <placement-id> --org <org-id>
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td>`--id string`</td><td>Placement ID or name</td></tr>
    <tr><td>`--org string`</td><td>Organization ID or name</td></tr>

    <tr>
      <td>
        `--json`
      </td>

      <td>Emit the full JSON payload (mutually exclusive with `-q`)</td>
    </tr>

    <tr>
      <td>
        `-q, --query stringArray`
      </td>

      <td>jq filter for value extraction (see [Query output with `-q`](https://docs.nscale.com/docs/cli/query-output))</td>
    </tr>
  </tbody>
</table>

### Example

```bash theme={null}
nscale placements get <placement-id> -q '.status.readyHostCount' -q '.spec.count'
```

***

## create

Create a new placement. Accepts input from a JSON file or stdin, with an optional cloud-init configuration for the placed servers.

An SSH certificate authority is optional. To bind one, set the payload's `spec.serverSpec.sshCertificateAuthorityId` field or pass `--ssh-ca-id`, which overrides the payload. Use [`nscale ssh-cas list`](https://docs.nscale.com/docs/cli/ssh-cas#list) to find it. Passing `--ssh-ca-id ""` removes an SSH CA set in the payload. When you create a placement interactively and your organization has SSH CAs, the CLI asks whether to bind one.

```bash theme={null}
nscale placements create [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td>`-f, --file string`</td><td>Path to a JSON file</td></tr>
    <tr><td>`--stdin`</td><td>Read JSON from standard input</td></tr>
    <tr><td>`--cloud-init-path string`</td><td>Path to a cloud-init YAML file</td></tr>
    <tr><td>`--ssh-ca-id string`</td><td>SSH certificate authority ID or name to bind</td></tr>
    <tr><td>`--dry-run`</td><td>Preview actions and payload without persisting</td></tr>
    <tr><td>`-y, --yes`</td><td>Automatically confirm placement creation</td></tr>

    <tr>
      <td>
        `--json`
      </td>

      <td>Emit the full JSON payload (mutually exclusive with `-q`)</td>
    </tr>

    <tr>
      <td>
        `-q, --query stringArray`
      </td>

      <td>jq filter for value extraction (see [Query output with `-q`](https://docs.nscale.com/docs/cli/query-output))</td>
    </tr>
  </tbody>
</table>

### Examples

```bash theme={null}
nscale placements create --file placement.json
nscale placements create --stdin < placement.json
cat placement.json | nscale placements create --stdin
nscale placements create --file placement.json --cloud-init-path cloud-init.yaml
nscale placements create --file placement.json --ssh-ca-id <ssh-ca-id>
```

***

## update

Change a placement's server image or update strategy. The CLI reads the placement, changes only the image and strategy, and writes it back, keeping every other field. All other placement fields are fixed after creation. Scripts pass `--image`, `--strategy`, or both. In a terminal, the CLI asks for what you leave out, as described below.

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`](#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. On a `manual` placement, an interactive run asks whether to roll the new image out instead, and how many servers to rebuild at once. With `--yes`, or outside a terminal, it keeps `manual`.

`--image` takes an image ID or name from the placement's region. When the reservation reports its hosts' CPU architecture, the CLI refuses an image built for a different one. When it doesn't, any image in the region is accepted, and the API doesn't check either, so confirm the architecture yourself before a rebuild. Without `--image` or `--strategy`, an interactive run lets you pick from the images the hosts can boot.

> [!WARNING]
>
> 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.

```bash theme={null}
nscale placements update <placement-id> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td>`--id string`</td><td>Placement ID or name</td></tr>
    <tr><td>`--org string`</td><td>Organization ID or name</td></tr>
    <tr><td>`--image string`</td><td>Image ID or name to converge the servers onto, from the placement's region and host architecture</td></tr>
    <tr><td>`--strategy string`</td><td>Update strategy: `manual` or `rolling`. The API's spellings, `Manual` and `RollingUpdate`, also work.</td></tr>
    <tr><td>`--max-unavailable string`</td><td>Servers rebuilt at once under `--strategy rolling`: a count (`1`) or a percentage of the placement's servers (`25%`, rounded up)</td></tr>
    <tr><td>`--dry-run`</td><td>Preview actions and payload without persisting</td></tr>
    <tr><td>`-y, --yes`</td><td>Automatically confirm placement update</td></tr>

    <tr>
      <td>
        `--json`
      </td>

      <td>Emit the full JSON payload (mutually exclusive with `-q`)</td>
    </tr>

    <tr>
      <td>
        `-q, --query stringArray`
      </td>

      <td>jq filter for value extraction (see [Query output with `-q`](https://docs.nscale.com/docs/cli/query-output))</td>
    </tr>
  </tbody>
</table>

### Examples

```bash theme={null}
# Roll a new image out, one server at a time
nscale placements update <placement-id> --image <image> --strategy rolling --max-unavailable 1 --yes

# Change the image but rebuild servers yourself with server reconcile
nscale placements update <placement-id> --image <image> --strategy manual --yes

# Preview the request body without sending it
nscale placements update <placement-id> --image <image> --dry-run
```

***

## delete

Delete an existing placement.

```bash theme={null}
nscale placements delete <placement-id> --org <org-id> [flags]
```

**Aliases:** `delete`, `rm`, `remove`

### Flags

| Flag | Description |
| - | - |
| `--id string` | Placement ID or name |
| `--org string` | Organization ID or name |
| `--dry-run` | Preview actions without persisting |
| `-y, --yes` | Automatically confirm placement delete |

### Example

```bash theme={null}
nscale placements delete <placement-id> --org <org-id> --yes
```

***

## server list

List the servers in a placement.

```bash theme={null}
nscale placements server list <placement-id> --org <org-id>
```

**Aliases:** `list`, `ls`

The table shows each server's name, private IP, GPUs, CPUs, and status, followed by a status summary line such as `Status summary: rebuilding: 1, running: 3`. The summary appears only in the human table; `--json`, `-q`, and the `agent` format are unchanged.

The status is one of `creating`, `ready`, `running`, `starting`, `stopping`, `stopped`, `queued`, `building`, `rebuilding`, `degraded`, `deleting`, `error`, or `unknown`. `rebuilding` means the server is being rebuilt onto a new image, for example by [`server reconcile`](#server-reconcile) or a `rolling` update. Any other power state reported by the service is shown in lowercase.

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td>`--id string`</td><td>Placement ID or name</td></tr>
    <tr><td>`--org string`</td><td>Organization ID or name</td></tr>

    <tr>
      <td>
        `--json`
      </td>

      <td>Emit the full JSON payload (mutually exclusive with `-q`)</td>
    </tr>

    <tr>
      <td>
        `-q, --query stringArray`
      </td>

      <td>jq filter for value extraction (see [Query output with `-q`](https://docs.nscale.com/docs/cli/query-output))</td>
    </tr>

    <tr>
      <td>
        `--limit int`
      </td>

      <td>Show at most N results (client-side; every result is still fetched). Cuts before `-q`. `0` for all</td>
    </tr>
  </tbody>
</table>

### Examples

```bash theme={null}
nscale placements server list <placement-id> -q '.[].metadata.name' -q '.[].status.privateIP'
```

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

```bash theme={null}
nscale placements server list <placement-id> \
  -q '.[] | select(.status.driftState == "Drifted") | .metadata.id'
```

***

## server reboot

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

```bash theme={null}
nscale placements server reboot <placement-id> --server <server-id> --org <org-id> [flags]
```

### Flags

| Flag | Description |
| - | - |
| `--id string` | Placement ID or name |
| `--server string` | Server ID or name |
| `--org string` | Organization ID or name |
| `--hard` | Use hard reboot |
| `--dry-run` | Preview actions and payload without persisting |
| `-y, --yes` | Automatically confirm server reboot |

### Examples

```bash theme={null}
nscale placements server reboot <placement-id> --server <server-id> --org <org-id> --yes
nscale placements server reboot <placement-id> --server <server-id> --hard --yes
```

***

## server stop

Stop an existing server in a placement.

```bash theme={null}
nscale placements server stop <placement-id> --server <server-id> --org <org-id> [flags]
```

### Flags

| Flag | Description |
| - | - |
| `--id string` | Placement ID or name |
| `--server string` | Server ID or name |
| `--org string` | Organization ID or name |
| `--dry-run` | Preview actions without persisting |
| `-y, --yes` | Automatically confirm server stop |

### Example

```bash theme={null}
nscale placements server stop <placement-id> --server <server-id> --org <org-id> --yes
```

***

## 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](#update) to move servers onto the new image one at a time. If the server already runs the placement's image, nothing changes.

```bash theme={null}
nscale placements server reconcile <placement-id> --server <server-id> --org <org-id> [flags]
```

### Flags

| Flag | Description |
| - | - |
| `--id string` | Placement ID or name |
| `--server string` | Server ID or name |
| `--org string` | Organization ID or name |
| `--dry-run` | Preview actions without persisting |
| `-y, --yes` | Automatically confirm server reconcile |

### Example

```bash theme={null}
nscale placements server reconcile <placement-id> --server <server-id> --org <org-id> --yes
```

***

## Related

> [card] [Reservations](https://docs.nscale.com/docs/cli/reservations.md)
>
> Reserve GPU capacity and check available reservation units.
