> ## 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`

<Note>
  Placements are gated behind a feature flag. The `placements` command is hidden and unavailable unless the feature is enabled for your organization.
</Note>

## Subcommands

* [list](#list) — List placements
* [get](#get) — Get placement details
* [create](#create) — Create a new placement
* [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

***

## 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 --id <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.

```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>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm 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
```

***

## delete

Delete an existing placement.

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

### Flags

| Flag           | Description                                    |
| -------------- | ---------------------------------------------- |
| `--id string`  | Placement ID                                   |
| `--org string` | Organization ID                                |
| `--dry-run`    | Preview the request payload without persisting |
| `-y, --yes`    | Automatically confirm deletion                 |

### Example

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

***

## servers

List the servers in a placement.

```bash theme={null}
nscale placements servers --id <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>

***

## server-reboot

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

```bash theme={null}
nscale placements server-reboot --id <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 the request payload without persisting |
| `-y, --yes`       | Automatically confirm reboot                   |

### Example

```bash theme={null}
nscale placements server-reboot --id <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 --id <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 the request payload without persisting |
| `-y, --yes`       | Automatically confirm stop                     |

### Example

```bash theme={null}
nscale placements server-stop --id <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>