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

# Reservations

> Manage GPU reservations.

**Aliases:** `reservations`, `reservation`, `res`

Commands that act on one reservation 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.

Reservation, project, and region flags accept a name as well as an ID.

## Subcommands

* [list](#list) — List reservations
* [get](#get) — Get reservation details
* [capacity](#capacity) — List available reservation units
* [topology](#topology) — Show organization topology
* [create](#create) — Create a new reservation
* [delete](#delete) — Delete a reservation

***

## list

List reservations, optionally filtered by organization, project, or region.

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

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

### 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>`--region string`</td><td>Region 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 reservations list --org <org-id> --region <region-id>
nscale reservations list -q '.[].metadata.id' -q '.[].spec.accelerator'
```

***

## get

Get details for a specific reservation.

```bash theme={null}
nscale reservations get <reservation-id> --org <org-id>
```

### Flags

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

  <tbody>
    <tr><td>`--id string`</td><td>Reservation 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 reservations get <reservation-id> -q '.spec.count' -q '.status.claimedUnitCount'
```

***

## capacity

List available reservation units, optionally filtered by region, accelerator model, or unit type. Useful for checking capacity before creating a reservation.

**Aliases:** `capacity`, `units`

```bash theme={null}
nscale reservations capacity [flags]
```

### Flags

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

  <tbody>
    <tr><td>`--region string`</td><td>Region ID or name</td></tr>
    <tr><td>`--accelerator string`</td><td>Accelerator model, for example `GB300`</td></tr>
    <tr><td>`--unit string`</td><td>Reservation unit, for example `NVL72`</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 reservations capacity --region <region-id> --accelerator GB300
nscale reservations capacity -q '.[].unit' -q '.[].availableUnitCount'
```

***

## topology

Show the bare-metal capacity allocated to your organization, laid out by region, pod, NVLink domain, and host, with the reservations and placements that hold it. This is the CLI counterpart to the Console's [Topology View](https://docs.nscale.com/docs/compute/topology-view.md). Filter by project, region, reservation, accelerator model, or unit type to narrow the output.

In human output, each reservation unit names its machine flavor, including [pinned-only flavors](https://docs.nscale.com/docs/cli/flavors.md#pinned-only-flavors) that only reserved capacity can use.

```bash theme={null}
nscale reservations topology [flags]
```

> [!NOTE]
>
> **Organization-level access required.** Like the Topology View, this command needs organization-level read access to reservation topology, for example the **reservation-capacity-reader** role assigned at organization level. See [Roles and groups](https://docs.nscale.com/docs/manage/roles-and-groups.md#reservations). If topology isn't enabled for your organization, the command fails with `the "topology" command is not available for organization <org-id>`.

### Flags

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

  <tbody>
    <tr><td>`--project string`</td><td>Project ID or name</td></tr>
    <tr><td>`--region string`</td><td>Region ID or name</td></tr>
    <tr><td>`--reservation string`</td><td>Reservation ID or name</td></tr>
    <tr><td>`--accelerator string`</td><td>Accelerator model, for example `GB300`</td></tr>
    <tr><td>`--unit string`</td><td>Reservation unit, for example `NVL72`</td></tr>
    <tr><td>`--view string`</td><td>Human output view: `tree` or `grid` (default `tree`). Has no effect on `--json` or `-q` output</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}
# Tree view of everything allocated to the organization
nscale reservations topology --org <org-id>

# Grid view of one reservation's hosts
nscale reservations topology --reservation <reservation-id> --view grid

# GB300 capacity in one region, as JSON
nscale reservations topology --region <region-id> --accelerator GB300 --json
```

***

## create

Create a new reservation. Accepts input from a JSON file or stdin.

```bash theme={null}
nscale reservations 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>`--dry-run`</td><td>Preview actions and payload without persisting</td></tr>
    <tr><td>`-y, --yes`</td><td>Automatically confirm 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 reservations create --file reservation.json
nscale reservations create --stdin < reservation.json
cat reservation.json | nscale reservations create --stdin
```

***

## delete

Delete an existing reservation.

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

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

### Flags

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

### Example

```bash theme={null}
nscale reservations delete <reservation-id> --org <org-id> --yes
```

***

## Related

> [card] [Placements](https://docs.nscale.com/docs/cli/placements.md)
>
> Place workloads onto reserved capacity and manage their servers.

> [card] [Topology View](https://docs.nscale.com/docs/compute/topology-view.md)
>
> See allocated capacity as a map in the Console.
