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

# Placements

> Manage GPU placements.

export const resource_0 = "placement"

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

Commands that act on one {resource_0} 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) — 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
* [servers](#servers) — 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

***

## list

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

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

### Flags

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

  <tbody>
    <tr><td><code>{"--org string"}</code></td><td>Organization ID</td></tr>
    <tr><td><code>{"--project string"}</code></td><td>Project ID</td></tr>
    <tr><td><code>{"--reservation string"}</code></td><td>Reservation ID</td></tr>

    <tr>
      <td>
        <code>
          {"--json"}
        </code>
      </td>

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

    <tr>
      <td>
        <code>
          {"-q, --query stringArray"}
        </code>
      </td>

      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Example

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

***

## 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><code>{"--id string"}</code></td><td>Placement ID</td></tr>
    <tr><td><code>{"--org string"}</code></td><td>Organization ID</td></tr>

    <tr>
      <td>
        <code>
          {"--json"}
        </code>
      </td>

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

    <tr>
      <td>
        <code>
          {"-q, --query stringArray"}
        </code>
      </td>

      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

***

## 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`](/docs/cli/ssh-cas#list) to find the ID.

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

### Flags

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

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

    <tr>
      <td>
        <code>
          {"--json"}
        </code>
      </td>

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

    <tr>
      <td>
        <code>
          {"-q, --query stringArray"}
        </code>
      </td>

      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</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 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`](#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.

<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.
</Warning>

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

### Flags

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

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

    <tr>
      <td>
        <code>
          {"--json"}
        </code>
      </td>

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

    <tr>
      <td>
        <code>
          {"-q, --query stringArray"}
        </code>
      </td>

      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</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-id> --strategy rolling --max-unavailable 1 --yes

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

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

***

## delete

Delete an existing placement.

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

### Flags

| Flag | Description |
| - | - |
| `--id string` | Placement ID |
| `--org string` | Organization ID |
| `--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
```

***

## servers

List the servers in a placement.

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

### Flags

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

  <tbody>
    <tr><td><code>{"--id string"}</code></td><td>Placement ID</td></tr>
    <tr><td><code>{"--org string"}</code></td><td>Organization ID</td></tr>

    <tr>
      <td>
        <code>
          {"--json"}
        </code>
      </td>

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

    <tr>
      <td>
        <code>
          {"-q, --query stringArray"}
        </code>
      </td>

      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Example

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 servers <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 |
| `--server string` | Server ID |
| `--org string` | Organization ID |
| `--hard` | Use hard reboot |
| `--dry-run` | Preview actions and payload without persisting |
| `-y, --yes` | Automatically confirm server reboot |

### Example

```bash theme={null}
nscale placements server-reboot <placement-id> --server <server-id> --org <org-id> --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 |
| `--server string` | Server ID |
| `--org string` | Organization ID |
| `--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 |
| `--server string` | Server ID |
| `--org string` | Organization ID |
| `--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

<CardGroup cols={2}>
  <Card title="Reservations" icon="calendar-check" href="/docs/cli/reservations">
    Reserve GPU capacity and check available reservation units.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.