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

# Instances

> Manage compute instances.

**Aliases:** `instances`, `inst`

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

## Subcommands

* [list](#list) — List instances
* [get](#get) — Get instance details
* [create](#create) — Create a new instance
* [update](#update) — Update an existing instance
* [delete](#delete) — Delete an instance
* [start](#start) — Start an instance
* [stop](#stop) — Stop an instance
* [reboot](#reboot) — Reboot an instance
* [snapshot](#snapshot) — Create a snapshot from an instance
* [ssh](#ssh) — Open an SSH session to an instance
* [ssh-key](#ssh-key) — Get an instance's SSH key
* [console-output](#console-output) — Get instance console output
* [console-session](#console-session) — Get a VNC console session URL

***

## list

List compute instances, optionally filtered by organization, project, network, or region.

```bash theme={null}
nscale instances 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>`--network string`</td><td>Network ID or name</td></tr>
    <tr><td>`--region string`</td><td>Region ID or name</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>

    <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 instances list --project <project-id> --region <region-id>
nscale instances list -q '.[].metadata.id' -q '.[].status.publicIP'
nscale instances list --network <network-id> --json
```

***

## get

Get details for a specific instance.

```bash theme={null}
nscale instances get <instance-id>
```

### Flags

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

  <tbody>
    <tr><td>`--id string`</td><td>Instance 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>

***

## create

Create a new compute instance. Accepts input from a JSON file or stdin; with neither, the CLI prompts for the instance details. Optionally supply a cloud-init configuration or bind an SSH certificate authority.

Provisioning is asynchronous: the API accepts the request and builds the instance in the background. Pass `--wait` to block until it is running.

```bash theme={null}
nscale instances 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 (pass empty string to clear)</td></tr>
    <tr><td>`--wait`</td><td>Block until provisioning finishes</td></tr>
    <tr><td>`--wait-timeout duration`</td><td>How long `--wait` polls before giving up; the operation keeps running server-side (default `30m0s`)</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 instances create --file instance.json
nscale instances create --stdin < instance.json
cat instance.json | nscale instances create --stdin
nscale instances create --file instance.json --yes --wait
```

***

## update

Update an existing instance. Accepts input from a JSON file or stdin; with neither, the CLI prompts for the fields to change. You can update the description and other mutable fields, but the instance **name is immutable** — it cannot be changed after creation.

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

### Flags

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

  <tbody>
    <tr><td>`--id string`</td><td>Instance ID or name</td></tr>
    <tr><td>`--org string`</td><td>Organization ID or name</td></tr>
    <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>`--ssh-ca-id string`</td><td>SSH certificate authority ID or name to bind (pass empty string to clear)</td></tr>
    <tr><td>`--dry-run`</td><td>Preview actions and payload without persisting</td></tr>
    <tr><td>`-y, --yes`</td><td>Automatically confirm 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}
nscale instances update <instance-id> --file instance.json
nscale instances update <instance-id> --stdin < instance.json
cat instance.json | nscale instances update <instance-id> --stdin
```

***

## delete

Delete an existing instance. Teardown is asynchronous: the instance disappears some time after the API accepts the request. Pass `--wait` to block until it is gone.

```bash theme={null}
nscale instances delete <instance-id> [flags]
```

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

### Flags

| Flag | Description |
| - | - |
| `--id string` | Instance ID or name |
| `--org string` | Organization ID or name |
| `--wait` | Block until deletion finishes |
| `--wait-timeout duration` | How long `--wait` polls before giving up; the operation keeps running server-side (default `30m0s`) |
| `--dry-run` | Preview actions and payload without persisting |
| `-y, --yes` | Automatically confirm deletion |

### Examples

```bash theme={null}
nscale instances delete <instance-id> --yes
nscale instances delete <instance-id> --yes --wait
```

***

## start

Start a stopped instance. The power change is asynchronous; pass `--wait` to block until the instance is running.

```bash theme={null}
nscale instances start <instance-id> [flags]
```

### Flags

| Flag | Description |
| - | - |
| `--id string` | Instance ID or name |
| `--org string` | Organization ID or name |
| `--wait` | Block until the instance is running |
| `--wait-timeout duration` | How long `--wait` polls before giving up; the operation keeps running server-side (default `30m0s`) |
| `--dry-run` | Preview actions and payload without persisting |
| `-y, --yes` | Automatically confirm start |

***

## stop

Stop a running instance. The power change is asynchronous; pass `--wait` to block until the instance is stopped.

```bash theme={null}
nscale instances stop <instance-id> [flags]
```

### Flags

| Flag | Description |
| - | - |
| `--id string` | Instance ID or name |
| `--org string` | Organization ID or name |
| `--wait` | Block until the instance is stopped |
| `--wait-timeout duration` | How long `--wait` polls before giving up; the operation keeps running server-side (default `30m0s`) |
| `--dry-run` | Preview actions and payload without persisting |
| `-y, --yes` | Automatically confirm stop |

***

## reboot

Reboot an instance. Use `--hard` for a hard reboot.

```bash theme={null}
nscale instances reboot <instance-id> [flags]
```

### Flags

| Flag | Description |
| - | - |
| `--id string` | Instance 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 reboot |

***

## snapshot

Create an image snapshot from an instance. Accepts input from a JSON file or stdin; with neither, the CLI prompts for the snapshot name and description. The image is captured asynchronously; pass `--wait` to block until it is ready.

```bash theme={null}
nscale instances snapshot <instance-id> [flags]
```

### Flags

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

  <tbody>
    <tr><td>`--id string`</td><td>Instance ID or name</td></tr>
    <tr><td>`--org string`</td><td>Organization ID or name</td></tr>
    <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>`--wait`</td><td>Block until capture finishes</td></tr>
    <tr><td>`--wait-timeout duration`</td><td>How long `--wait` polls before giving up; the operation keeps running server-side (default `30m0s`)</td></tr>
    <tr><td>`--dry-run`</td><td>Preview actions and payload without persisting</td></tr>
    <tr><td>`-y, --yes`</td><td>Automatically confirm snapshot</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 instances snapshot <instance-id> --file snapshot.json
nscale instances snapshot <instance-id> --stdin < snapshot.json
cat snapshot.json | nscale instances snapshot <instance-id> --stdin
nscale instances snapshot <instance-id> --file snapshot.json --yes --wait
```

***

## ssh

Open an interactive SSH session to an instance using the system SSH client.

```bash theme={null}
nscale instances ssh <instance-id> [flags]
```

### Flags

| Flag | Description |
| - | - |
| `--id string` | Instance ID or name |
| `--org string` | Organization ID or name |
| `-l, --ssh-user string` | SSH login user (default: `"root"`) |

### Examples

```bash theme={null}
nscale instances ssh <instance-id>
nscale instances ssh <instance-id> --ssh-user ubuntu
nscale instances ssh <instance-id> -l ubuntu
nscale instances ssh <instance-id> -- -L 8443:127.0.0.1:443
```

***

## ssh-key

Get the SSH key for an instance.

```bash theme={null}
nscale instances ssh-key <instance-id>
```

**Aliases:** `ssh-key`, `sshkey`

### Flags

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

  <tbody>
    <tr><td>`--id string`</td><td>Instance 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 instances ssh-key <instance-id> -q '.privateKey' > instance-key.pem
```

***

## console-output

Retrieve the serial console output of an instance.

```bash theme={null}
nscale instances console-output <instance-id> [flags]
```

**Aliases:** `console-output`, `consoleoutput`

### Flags

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

  <tbody>
    <tr><td>`--id string`</td><td>Instance ID or name</td></tr>
    <tr><td>`--org string`</td><td>Organization ID or name</td></tr>
    <tr><td>`--length int`</td><td>Output length in bytes (0 uses API default)</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 instances console-output <instance-id> --length 4096
nscale instances console-output <instance-id> -q '.contents'
```

***

## console-session

Get a VNC console session URL for an instance.

```bash theme={null}
nscale instances console-session <instance-id>
```

**Aliases:** `console-session`, `consolesession`

### Flags

| Flag | Description |
| - | - |
| `--id string` | Instance ID or name |
| `--org string` | Organization ID or name |

***

## Related

> [card] [Instances (Console)](https://docs.nscale.com/docs/compute/create-new-instances.md)
>
> Create and manage instances via the Console UI.

> [card] [Custom Images](https://docs.nscale.com/docs/storage/custom-images.md)
>
> Upload and use custom OS images for instances.
