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

# File storage

> Manage file storage resources.

export const resource_0 = "file storage resource"

**Aliases:** `filestorage`, `fs`

Manage [file storage](/docs/storage/file-storage): shared NFS filesystems that instances and Kubernetes clusters on the same network can mount. Every command acts in the organization given by `--org`, or the one saved in your [context](/docs/cli/contexts).

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 file storage resources
* [classes](#classes) — List file storage classes
* [get](#get) — Get file storage details
* [create](#create) — Create a new file storage resource
* [update](#update) — Update an existing file storage resource
* [delete](#delete) — Delete a file storage resource

**Snapshot policies** (aliases: `snapshot-policy`, `sp`)

* [snapshot-policy list](#snapshot-policy-list) — List snapshot policies for a file storage resource
* [snapshot-policy create](#snapshot-policy-create) — Create a snapshot policy for a file storage resource
* [snapshot-policy update](#snapshot-policy-update) — Update a snapshot policy on a file storage resource
* [snapshot-policy delete](#snapshot-policy-delete) — Delete a snapshot policy from a file storage resource

***

## list

List file storage resources, optionally filtered by project or region. The table shows each resource's ID, name, region, size in GiB, and remote ports.

**Remote Ports** is the IP range of the NFS storage endpoints for each network attachment, ready to use as the `remoteports` mount option. It's empty until an attachment has been given a range.

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

### Examples

```bash theme={null}
nscale filestorage list --region <region-id>
nscale filestorage list --project <project-id> -q '.[].metadata.id'
```

***

## classes

List the file storage classes you can create file storage in. A class sets the kind of storage and the region it lives in. Pass its ID as `spec.storageClassId` when you [create](#create) a file storage resource. The table shows each class's ID, name, region, supported protocols, and parallelism.

```bash theme={null}
nscale filestorage classes [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>{"--region string"}</code></td><td>Region ID (defaults to all regions)</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 filestorage classes --region <region-id>
nscale filestorage classes --region <region-id> -q '.[].metadata.id'
```

***

## get

Get details for a file storage resource, including its NFS settings, snapshot policies, and network attachments. Each attachment in `status.attachments` carries its `mountSource`, in `<host>:<path>` format, and its `mountOptions`.

```bash theme={null}
nscale filestorage get <storage-id> [flags]
```

### Flags

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

  <tbody>
    <tr><td><code>{"--id string"}</code></td><td>File storage ID. Can also be passed as a positional argument</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>

### Examples

```bash theme={null}
nscale filestorage get <storage-id> --json
nscale filestorage get <storage-id> -q '.status.attachments[].mountSource'
```

***

## create

Create a new file storage resource. Accepts input from a JSON file or stdin. With neither, the CLI prompts for the name, description, project, region, size (1 to 1013 GiB), NFS settings, networks to attach, and Default Snapshot Protection. It offers only regions that have a file storage class, and uses the first class it finds in the region you choose. To choose the [class](#classes) yourself or add [snapshot policies](#snapshot-policies), use a file.

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

Example payload:

```json storage.json theme={null}
{
  "metadata": {
    "name": "shared-data"
  },
  "spec": {
    "organizationId": "<org-id>",
    "projectId": "<project-id>",
    "regionId": "<region-id>",
    "storageClassId": "<storage-class-id>",
    "sizeGiB": 200,
    "storageType": {
      "NFS": {
        "rootSquash": true,
        "posixAcl": false,
        "atimeUpdateIntervalSeconds": 0
      }
    },
    "attachments": {
      "networkIds": ["<network-id>"]
    }
  }
}
```

| Field | Notes |
| - | - |
| `spec.storageClassId` | A class from the same region. List them with [`classes`](#classes). |
| `spec.storageType.NFS` | `rootSquash` is required. `posixAcl` and `atimeUpdateIntervalSeconds` are optional and default to `false` and `0`. See [NFS settings](/docs/storage/file-storage#nfs-settings) for what each does. The CLI rejects an `atime` interval outside the accepted range before sending the request. |
| `spec.attachments.networkIds` | Optional. The networks the file storage is mounted from. |
| `spec.defaultSnapshotProtectionEnabled` | Optional. Omit it to turn on Default Snapshot Protection, or set `false` to leave it off. |
| `spec.snapshotPolicies` | Optional. User-managed [snapshot policies](/docs/storage/file-storage#snapshot-policies), up to 4. |

### 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 filestorage create --file storage.json
nscale filestorage create --stdin < storage.json
cat storage.json | nscale filestorage create --stdin
```

***

## update

Update an existing file storage resource. Accepts input from a JSON file or stdin. With neither, the CLI prompts for the name, description, size, NFS settings, networks, and Default Snapshot Protection, pre-filled from the resource as it stands. The prompts leave snapshot policies unchanged; manage them with the [`snapshot-policy`](#snapshot-policies) commands.

A payload takes `metadata` and the `spec` fields from [`create`](#create) except `organizationId`, `projectId`, `regionId`, and `storageClassId`. It replaces the resource's settings, with these exceptions for omitted fields:

| Field | When omitted |
| - | - |
| `spec.storageType.NFS.posixAcl` | Resets to `false` |
| `spec.storageType.NFS.atimeUpdateIntervalSeconds` | Resets to `0` |
| `spec.defaultSnapshotProtectionEnabled` | Keeps the current setting |
| `spec.snapshotPolicies` | Keeps the current policies. Send `[]` to remove them all, or a list to replace them all. |

If your payload leaves out `posixAcl` or `atimeUpdateIntervalSeconds` while the resource has them set, the CLI prints a warning on stderr before sending it, including with `--dry-run`. The payload is still sent as written. To keep the current values, start from `nscale filestorage get <storage-id> --json`.

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

### Flags

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

  <tbody>
    <tr><td><code>{"--id string"}</code></td><td>File storage ID. Can also be passed as a positional argument</td></tr>
    <tr><td><code>{"--org string"}</code></td><td>Organization ID</td></tr>
    <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 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}
nscale filestorage update <storage-id> --file storage.json
nscale filestorage update <storage-id> --stdin < storage.json
cat storage.json | nscale filestorage update <storage-id> --stdin
```

***

## delete

Delete a file storage resource.

<Warning>
  Deleting file storage permanently removes all its data and snapshots. This can't be undone.
</Warning>

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

### Flags

| Flag | Description |
| - | - |
| `--id string` | File storage ID. Can also be passed as a positional argument |
| `--org string` | Organization ID |
| `--dry-run` | Preview actions and payload without persisting |
| `-y, --yes` | Automatically confirm deletion |

### Example

```bash theme={null}
nscale filestorage delete <storage-id> --yes
```

***

## Snapshot policies

Snapshot policies take point-in-time snapshots of a file storage resource on a schedule and keep a set number of them. Each resource can have up to **4** policies. For how schedules and retention work, see [Snapshot policies](/docs/storage/file-storage#snapshot-policies).

The `snapshot-policy` commands edit the policies stored on the file storage resource. Each change reads the resource and sends it back with the updated policy list. The rest of the resource is left as it is, including Default Snapshot Protection. Default Snapshot Protection is managed by Nscale and doesn't appear in these commands.

`create` and `update` collect the policy through interactive prompts and don't accept a JSON file, so they need a terminal. With `--ci`, they fail. To set policies in a script, send the full `spec.snapshotPolicies` list with [`update`](#update) instead.

The prompts ask for:

| Prompt | Shown for | Rules |
| - | - | - |
| **Name** | Every policy | Lowercase letters, numbers, and dashes; at most 19 characters; unique on the resource |
| **Frequency** | Every policy | `Hourly`, `Daily`, `Weekly`, or `Monthly` |
| **Day of week** | Weekly | `Monday` through `Sunday` |
| **Day of month** | Monthly | `1` through `28`, so the policy runs every month |
| **Time of day (UTC)** | Daily, weekly, monthly | 24-hour `HH:MM` |
| **Latest snapshots to keep** | Every policy | At least `1`. Older snapshots are deleted automatically. |

***

## snapshot-policy list

List the snapshot policies on a file storage resource. The table shows each policy's name, frequency, run time, number of snapshots kept, and provisioning status.

With `--json` or `-q`, the output is the array of policies from `spec.snapshotPolicies`. Each policy has `name`, `schedule`, and `retention` fields, with no `metadata` wrapper.

```bash theme={null}
nscale filestorage snapshot-policy list <storage-id> [flags]
```

### Flags

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

  <tbody>
    <tr><td><code>{"--id string"}</code></td><td>File storage ID. Can also be passed as a positional argument</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>

### Examples

```bash theme={null}
nscale filestorage snapshot-policy list <storage-id>
nscale fs sp list <storage-id> -q '.[].name'
```

***

## snapshot-policy create

Add a snapshot policy to a file storage resource. The CLI [prompts](#snapshot-policies) for the policy's name, schedule, and retention, then asks you to confirm. It fails if the resource already has 4 policies.

On success, the updated file storage resource is printed.

```bash theme={null}
nscale filestorage snapshot-policy create <storage-id> [flags]
```

### Flags

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

  <tbody>
    <tr><td><code>{"--id string"}</code></td><td>File storage ID. Can also be passed as a positional argument</td></tr>
    <tr><td><code>{"--org string"}</code></td><td>Organization ID</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>

### Example

```bash theme={null}
nscale filestorage snapshot-policy create <storage-id>
```

***

## snapshot-policy update

Change a snapshot policy's name, schedule, or retention. The CLI [prompts](#snapshot-policies) for each field, pre-filled from the policy as it stands, then asks you to confirm. If you omit `--name`, you pick the policy from a list.

Policy names identify policies in the API, so renaming a policy replaces it with a new one.

On success, the updated file storage resource is printed.

```bash theme={null}
nscale filestorage snapshot-policy update <storage-id> --name <policy-name> [flags]
```

### Flags

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

  <tbody>
    <tr><td><code>{"--id string"}</code></td><td>File storage ID. Can also be passed as a positional argument</td></tr>
    <tr><td><code>{"--org string"}</code></td><td>Organization ID</td></tr>
    <tr><td><code>{"--name string"}</code></td><td>Name of the snapshot policy to update (prompts if omitted)</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 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>

### Example

```bash theme={null}
nscale filestorage snapshot-policy update <storage-id> --name daily
```

***

## snapshot-policy delete

Remove a snapshot policy from a file storage resource. If you omit `--name`, you pick the policy from a list.

```bash theme={null}
nscale filestorage snapshot-policy delete <storage-id> --name <policy-name> [flags]
```

### Flags

| Flag | Description |
| - | - |
| `--id string` | File storage ID. Can also be passed as a positional argument |
| `--org string` | Organization ID |
| `--name string` | Name of the snapshot policy to delete (prompts if omitted) |
| `--dry-run` | Preview actions and payload without persisting |
| `-y, --yes` | Automatically confirm deletion |

### Example

```bash theme={null}
nscale filestorage snapshot-policy delete <storage-id> --name daily --yes
```

***

## Related

<CardGroup cols={2}>
  <Card title="File Storage (Console)" icon="browser" href="/docs/storage/file-storage">
    Create and manage file storage via the Console UI.
  </Card>
</CardGroup>


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