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

# Reservations

> Manage GPU reservations.

export const resource_0 = "reservation"

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

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.

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

### 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>{"--region string"}</code></td><td>Region 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 reservations list --org <org-id> --region <region-id>
```

***

## 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><code>{"--id string"}</code></td><td>Reservation 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>

***

## capacity

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

**Alias:** `units`

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

### Flags

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

  <tbody>
    <tr><td><code>{"--region string"}</code></td><td>Region ID</td></tr>
    <tr><td><code>{"--accelerator string"}</code></td><td>Accelerator model, for example <code>GB300</code></td></tr>
    <tr><td><code>{"--unit string"}</code></td><td>Reservation unit, for example <code>NVL72</code></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 reservations capacity --region <region-id> --accelerator GB300
```

***

## 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](/docs/compute/topology-view). 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](/docs/cli/flavors#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](/docs/manage/roles-and-groups#reservations). If topology isn't enabled for your organization, the command fails with `the "topology" command is not available for organization <org-id>`.
</Note>

### Flags

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

  <tbody>
    <tr><td><code>{"--project string"}</code></td><td>Project ID</td></tr>
    <tr><td><code>{"--region string"}</code></td><td>Region ID</td></tr>
    <tr><td><code>{"--reservation string"}</code></td><td>Reservation ID</td></tr>
    <tr><td><code>{"--accelerator string"}</code></td><td>Accelerator model, for example <code>GB300</code></td></tr>
    <tr><td><code>{"--unit string"}</code></td><td>Reservation unit, for example <code>NVL72</code></td></tr>
    <tr><td><code>{"--view string"}</code></td><td>Human output view: <code>tree</code> or <code>grid</code> (default <code>tree</code>). Has no effect on <code>{"--json"}</code> or <code>-q</code> output</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}
# 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><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>{"--dry-run"}</code></td><td>Preview actions and 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 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]
```

### Flags

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

<CardGroup cols={2}>
  <Card title="Placements" icon="server" href="/docs/cli/placements">
    Place workloads onto reserved capacity and manage their servers.
  </Card>

  <Card title="Topology View" icon="diagram-project" href="/docs/compute/topology-view">
    See allocated capacity as a map in the Console.
  </Card>
</CardGroup>


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